Run Sitecore Personalize personalizations

Current version: 0.3

Using the Cloud SDK, you can personalize content for your site visitors by, for example, running interactive experiences that are live in Sitecore Personalize. To run this type of experience in your JSS Next.js app, you use the browser module of the Cloud SDK personalize package. Running the experience will return an API response, which contains the personalized content.

Note

XM Cloud personalizations run automatically in JSS Next.js apps, with no coding required.

This walkthrough describes how to:

Before you begin

Install and initialize @sitecore-cloudsdk/personalize/browser

The first step to running personalization is to install the @sitecore-cloudsdk/personalize package and initialize its browser module in your app.

To install the package and initialize the module:

  1. In your code editor, in the sxastarter folder, open the terminal and install the personalize package by running the following command:

    RequestResponse
    npm install @sitecore-cloudsdk/personalize
    
  2. In src/pages/[[...path]].tsx, import the initializer function of the browser module:

    RequestResponse
    import { init } from "@sitecore-cloudsdk/personalize/browser";
    

    src/pages/[[...path]].tsx is a catch-all route. The code you add to it will run on all the webpages of your app.

  3. Inside the SitecorePage constant, directly before the return statement, paste the following code then save your changes:

    RequestResponse
    const initPersonalize = async () => {
        await init({
            sitecoreEdgeContextId: "<YOUR_CONTEXT_ID>",
            siteName: "<YOUR_SITE_NAME>",
            enableBrowserCookie: true,
        });
    
        console.log("Initialized the personalize/browser module.");
    };
    
    initPersonalize();
    

    Replace the placeholder values with environment variable values from your XM Cloud instance.

    This code initializes the module using your Context ID and site name, and it sets cookies from the browser side.

Find the friendly ID in Sitecore Personalize

After initializing the module, you need to find the friendly ID of the live interactive experience you want to run on your site.

To find the friendly ID:

  1. In Sitecore Personalize, click Experiences.

  2. Click the live interactive experience you want to run.

  3. On the page of the experience, click Build summary. The friendly ID is in the Details pane.

    The friendly ID of an interactive experience.
  4. Make a note of the friendly ID. You'll use it in the next procedure to run the experience.

Run the experience on your site

After finding the friendly ID of the experience, you return to your code editor and run the experience on your site.

To run the experience:

  1. In your code editor, in src/pages/[[...path]].tsx, modify the import statement for the personalize/browser module to also import the personalize function:

    RequestResponse
    import { init, personalize } from "@sitecore-cloudsdk/personalize/browser";
    
    Note

    In production, you typically run the personalize function in the component you want to personalize, not in [[...path]].tsx .

  2. Inside the initPersonalize function, directly after the existing console.log() statement, paste the following code:

    RequestResponse
    const personalizeResponse = await personalize({
      channel: "<YOUR_CHANNEL>", // example: "WEB"
      currency: "<YOUR_CURRENCY>", // example: "EUR"
      friendlyId: "<YOUR_EXPERIENCE_FRIENDLY_ID>",
    });
    
    console.log("This experience is now running:", personalizeResponse);
    

    Replace the placeholder value with the friendly ID of your experience.

    See all the possible values for channel and currency in the reference documentation for the personalize package.

    This code runs the experience and logs its API response to the console.

  3. Save your changes.

Verify that the experience is running

After updating your code, it's a good idea to check that the experience is running on your site.

To verify that the experience is running:

  1. Start your rendering app by entering the following command in your terminal:

    RequestResponse
    npm run start:connected
    
  2. In your web browser, navigate to your JSS Next.js app, typically at http://localhost:3000.

  3. In your web browser's developer tools, on the Console tab, verify that you see the following logs in the console:

    RequestResponse
    Initialized the personalize/browser module.
    This experience is now running: {...}
    

    The second log contains the response that was created for this experience in Sitecore Personalize.

  4. In the developer tools, on the Network tab, in the Filter field, paste the following URL: https://edge-platform.sitecorecloud.io/personalize.

    This lists the network requests related to running your experience.

  5. In the list of requests, click a POST request that has the status of 200 OK.

  6. In the request details pane, click the Response tab for the request.

    The API response appears. This is the response that was created for this experience in Sitecore Personalize.

Next steps

You've now successfully run the experience on your site and received the API response for the experience in your app. You can now proceed to work with the response, for example, by displaying its content on your site.

Next, you can:

Do you have some feedback for us?

If you have suggestions for improving this article,