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.

Sample Usage

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

Shopper Context in PWA Kit

Prerequisites

To use personalization with Shopper Context:

Build your site with:
- The Retail React App template
- Retail React App version 5.0.0 or later
Have the Account Manager role of Business Manager Administrator. If you don’t have this role, ask your Account Manager Administrator to assign it to you. See Managing Account Manager for Salesforce B2C Commerce Users.
If you haven’t done so already, set up Authorization for Shopper APIs.
Set up your site based on the types of personalization that you want to use. For example, set up customer groups in Business Manager to apply rules for personalized pricing, products, or promotions.

Configure Shopper Context

1. Create a SLAS Private Client

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

2. Enable Shopper Context and Hooks

In Business Manager:

Enable Shopper Context. See Set and Retrieve Shopper Context.
Complete these Hooks Prerequisites.

3. Upload the shopper_context_hooks Cartridge

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.
1{ 2 "hostname": "$HOST.demandware.net", 3 "username": "$USERNAME", 4 "password": "$PASSWORD", 5 "code-version": "$VERSION" 6}
- 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).

4. Configure Custom Site Preferences

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.

5. Update the shopper_context_hooks Cartridge CLIENT_REGISTRY from Site Preferences

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.

1{
2  "aaaaaaaa-8536-4a39-acbb-8e7f1759f901": ["sourceCode", "geoLocation", "deviceType"],
3  "bbbbbbbb-b5e9-efbc-42f6-584f60fd54ff": ["all"]
4}

6. Add the Shopper Context Scope

Add this Shopper Context scope to the SLAS Private Client: sfcc.shopper-context.rw. See Create a SLAS Client.

Demo Implementation of Shopper Context

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.

1export const SHOPPER_CONTEXT_SEARCH_PARAMS = {
2   // These are the default query parameters.
3    sourceCode: {paramName: 'sourceCode'},
4    geoLocation: {
5        city: {paramName: 'city'},
6        country: {paramName: 'country'},
7        countryCode: {paramName: 'countryCode'},
8        latitude: {paramName: 'latitude', type: SHOPPER_CONTEXT_FIELD_TYPES.DOUBLE},
9        longitude: {paramName: 'longitude', type: SHOPPER_CONTEXT_FIELD_TYPES.DOUBLE},
10        metroCode: {paramName: 'metroCode'},
11        postalCode: {paramName: 'postalCode'},
12        region: {paramName: 'region'},
13        regionCode: {paramName: 'regionCode'}
14    },
15    // These are examples of custom query parameters that you can optionally add.
16    customQualifiers: {
17        deviceType: {paramName: 'deviceType'}
18    },
19    assignmentQualifiers: {
20        storeId: {paramName: 'storeId'}
21    }
22}, // More code here...

Extend Shopper Context

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.

1// ... Default imports in the hook
2import {useEffect, useState} from 'react'
3
4export const useUpdateShopperContext = () => {
5    // ... Default code in the hook
6    const [location, setLocation] = useState({latitude: null, longitude: null})
7
8     // Get the latitude and longitude of the shopper's geolocation using the browser's navigator.geolocation API.
9    const fetchLocation = () => {
10        if (typeof navigator !== 'undefined' && navigator.geolocation) {
11            navigator.geolocation.getCurrentPosition(
12                (position) => {
13                    setLocation({
14                        latitude: position.coords.latitude,
15                        longitude: position.coords.longitude
16                    })
17                },
18                (err) => {
19                    console.error(err.message) // Handle errors gracefully
20                },
21                {
22                    enableHighAccuracy: true, // Try to get the most accurate location
23                    timeout: 10000, // Time in milliseconds before timing out
24                    maximumAge: 60000 // Cache the location for 1 minute
25                }
26            )
27        } else {
28            console.error('Geolocation is not supported by this browser.')
29        }
30    }
31
32    fetchLocation()
33
34    // Update the Shopper Context when the latitude and/or longitude changes.
35    useEffect(() => {
36        if (location.latitude && location.longitude) {
37            const newShopperContext = {
38                geoLocation: {
39                    latitude: location.latitude,
40                    longitude: location.longitude
41                }
42            }
43            handleShopperContextUpdate(shopperContext, newShopperContext)
44        }
45    }, [location.latitude, location.longitude])
46}

Troubleshoot Shopper Context

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

Incorrect or Missing Personalization

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.