Personalize with Shopper Context

With Shopper Context, you can personalize shopping experiences by tailoring your promotions, pricing, product recommendations, and content delivered to your site based on shopper behavior. For example, if shoppers visit your site from a mobile device, offer them a 10% discount.

The hook named useUpdateShopperContext is used to set the Shopper Context in a Progressive Web App (PWA) Kit site. The default implementation of Shopper Context in PWA Kit is a demonstration of personalization capabilities. In the demo implementation described in this guide, we use query parameters to activate a personalization scheme that changes product listing page (PLP) content and promotions. Extend our implementation with custom code to match your own personalization strategy.

This guide explains our demo implementation of Shopper Context and how to configure and extend it to power the personalization strategy for your PWA Kit site. The functionality described in this guide isn’t supported in a hybrid storefront.

We recommend testing personalization in a non-production environment before deploying your changes to production. You can also preview your personalization using Storefront Preview.

Before running the commands in this guide, replace any placeholders with actual values. Placeholders are formatted like this: $PLACEHOLDER.

This video shows an example of how to personalize content and promotions with the demo implementation of Shopper Context.

Shopper Context in PWA Kit
undefined

To use personalization with Shopper Context:

  • In the Shopper Login and API Access (SLAS) Admin UI, create a SLAS private client. See Create a SLAS Client.

In Business Manager:

The shopper_context_hooks cartridge acts as an allowlist to ensure that only the context you want to use for personalization campaigns can be set from the client. In Business Manager:

  • Add shopper_context_hooks to your site’s cartridge path. This step ensures site security by preventing unauthorized members of your site development team from setting all Shopper Context scopes.

    • Go to Administration > Sites > Manage Sites.
    • Select the site where you want to use this cartridge. Example site identifier: RefArch.
    • Click the Settings tab.
    • In the Cartridges field, add the new cartridge path shopper_context_hooks. Add the new cartridge path before the path for app_storefront_base. For example: shopper_context_hooks:app_storefront_base

  • Install and upload the cartridge.

    • Clone the Shopper Context hooks repository. The name of the top-level directory is shopper_context_hooks.

    • To install package dependencies, from the shopper_context_hooks directory, run:

      npm install

    • Configure client IDs by updating CLIENT_REGISTRY in cartridges/shopper_context_hooks/cartridge/scripts/config/clientRegistry.js

    • Create a dw.json file in the shopper_context_hooks directory. Replace the $ strings in this example with actual values or set the corresponding environment variables.

    • From the shopper_context_hooks directory, run:

      npm run uploadCartridge

For more information about uploading the cartridge, see Upload Code for Storefront Reference Architecture (SFRA).

Configure the client registry by adding a custom site preference. To do so, import the system-objecttype-extensions.xml in Business Manager.

  • Go to Administration > Site Development > Import & Export.
  • Under Import & Export Files, click Upload.
  • Click Choose File.
  • Go to meta/meta.
  • Select system-objecttype-extensions.xml.
  • Click Upload.
  • After the file is uploaded, click Back.
  • Under Meta Data, click Import.
  • Select system-objecttype-extensions.xml and click Next.
  • After the file is validated, click Import.

To update your configuration, in Business Manager:

  • Go to Merchant Tools > Site Preferences > Custom Preferences > Shopper Context Hooks Preferences.
  • Update the Client Registry field with a JSON configuration. Enter your client ID that you set up in step 1 and the Shopper Context keys that the client can set. You can enter any of the keys available in the ShopperContext type. For client IDs that require permissions to set all Shopper Context keys, such as the client ID used for Storefront Preview, use the key all.

In this example, we set Shopper Context keys for two different client IDs.

  • Requests from client ID aaaaaaaa-8536-4a39-acbb-8e7f1759f901 can set only the 3 specified keys in Shopper Context.
  • Requests from client ID bbbbbbbb-b5e9-efbc-42f6-584f60fd54ff can set all keys in Shopper Context.
  • Add this Shopper Context scope to the SLAS Private Client: sfcc.shopper-context.rw. See Create a SLAS Client.

Our demo of Shopper Context uses the sourceCode set through a query parameter to trigger content changes on a PLP and new promotions for a specific customer group. You can see the demo in action on a PLP by adding &sourcecode=instagram to the URL.

In our demo we utilize the useUpdateShopperContext hook to trigger a personalization campaign. In your project, add or remove Shopper Context query parameters in the SHOPPER_CONTEXT_SEARCH_PARAMS constant in app/constants.js to achieve your own personalizations triggered by query parameters.

For example, if you added custom attributes that you want to be set using query parameters, include them as custom query parameters in app/constants.js. In this example, we add these parameters: deviceType and storeId.

Optionally, you can add personalization beyond what's in the Demo Implementation of Shopper Context. For example, you can personalize content based on a shopper’s geolocation.

In this sample code, we get a shopper's geolocation. After you get the geolocation, you can apply your chosen personalization. For example:

  • For New York, USA: 20% discount on women's tops.
  • For Boston, USA: 15% discount on women's tops.

This section provides a suggested solution for a common error that you can encounter while using Shopper Context.

Potential Cause: Personalization in Business Manager isn’t configured correctly.

Suggested Solution: Ensure that the context trigger you set is assigned to a personalization campaign in Business Manager.