Sitecore CDP & Personalize in Sitecore XM Cloud

Description

CDP and Personalize can be integrated with XM Cloud so you can get information from the users and also personalization on your site. There are 2 ways to get this integration working, the first one is using the instance that comes integrated by default in your XM site. The other option is to integrate a different CDP account into your site by hand. In both of them, you can get almost all the benefits of CDP and Personalize.

Default Account vs Custom Account

Default Account

Default Account

Configuration

You can get the configuration values from your XM Cloud Site. Go to your site settings

There you can go to Site Identifiers and create a point of sale. After that, you will see all the integration values in the Developer Settings Tab.

Initialization

Here you have already a snippet created which manages the injection of the engage library and the page views sent depending on variants of the pages. The only thing you need to do is add the CDP configurations in the .env file.

Personalize & Analize in Pages

There you can create different page variants and component variants depending on audiences directly in pages. This is what the variant id refers to, in the page view.In the analyze section you can get site and page insights as general information of visitors, average time of visit and bounce rate.

Access to Account

In order to have access to the default account you need to pay for CDP and Personalize. If you have already a different CDP and Personalize account, you need to get in contact with Sitecore so they can configure that account with your XM Cloud site.

Custom Account

Custom Account

Configuration

For this you need to go to your CDP instance and there get all the needed information requiered in the snippet of code that injects CDP and Personalize. First go to API Access in the account settings and there you can find the Client Key

Then you need to find the target endpoint. For that you need to see in the company information of your CDP account the environment. Depending on the environment you will choose the target URL. You can see them here: Collect required details.
Finally, you can go to create a point of sale for your site and the name of it will be the NEXT_PUBLIC_CDP_POINTOFSALE.

Initialization

In this case, you need to add all the configurations in the .env file but after that you need to change the CdpPageView.tsx file. If you review the file you can see that there is used a PosResolver (to resolve the ponit of sale), a siteResolver (to get the site info), and a CdpHelper (to get the page variant id). This are things that are only available if you use the default CDP account.This is our approach to integrate it:

const cookieDomain = window.location.host.includes('localhost:')
    ? 'localhost'
    : window.location.host.replace(/^www\./, '');
const engage = await init({
  clientKey: process.env.NEXT_PUBLIC_CDP_CLIENT_KEY || '',
  targetURL: process.env.NEXT_PUBLIC_CDP_TARGET_URL || '',
  pointOfSale: process.env.NEXT_PUBLIC_CDP_POINTOFSALE || '',
  cookieDomain: cookieDomain,
  forceServerCookieMode: false,
  webPersonalization: true,
});
const guestId = await engage.getGuestId();
setCookie('customerRef', guestId);
window.engage = engage;
const language = 'EN';
const path = window.location.pathname.toLocaleLowerCase();
const channel = 'WEB';
engage.pageView({
  channel,
  currency: 'USD',
  pointOfSale: process.env.NEXT_PUBLIC_CDP_POINTOFSALE as string,
  page: path,
  language,
});

Copy to clipboard

Personalize & Analize in Pages

You won’t be able neither to personalize nor see any of this data because you have connected a different instance than the one by default.

Access to Account

You can integrate any CDP account with any sites you need by adding the script.

Arquitecture

The arquitecture of CDP and Personalize in XM Cloud is really simple. The file which initializes the library needs to be called in all pages. That is way that file is called in a <Scripts /> component. And that script then is called in the layout of your site. This ensures that the engage library is loaded in all the pages of your site.

After you have initialized the engage library you need to expose it so you can use the functions in any part of your code. In order to do this you can just add engage to window or you can also add engage to the context of your app and use it anywhere.

Considerations

You might have some problems here if you use SSG (Static Site Generation). Sometimes the engage events are not triggered correctly. For example, in our site, we have product detail pages, and in all of them we send page views, but when you go through those pages the site never reloads (because of SSG) and this makes that the layout never change so the view event is not triggered any more.

In order to correct this it is necessary to add some logic where you are sending your events to trigger manually them again. In our example, everytime you go to a new product detail page, the URL change, so we created states for the path.

const [path, setPath] = useState("");
const [prevPath, setPrevPath] = useState("");

Then with the useEffect hook we trigger the event if the path change.

useEffect(() => {
  if (pageState !== LayoutServicePageState.Normal || !route?.itemId) {
    return;
  }
  // Update prevPath with the previous path value
  setPrevPath(router.asPath);
  // Review if path has changed
  if (prevPath !== path) {
    const language = 'EN';
    const path = window.location.pathname.toLocaleLowerCase();
    const channel = 'WEB';
    window.engage.pageView({
      channel,
      currency: 'USD',
      pointOfSale: process.env.NEXT_PUBLIC_CDP_POINTOFSALE as string,
      page: path,
      language,
    });
    setPath(router.asPath);
  }
}, [pageState, route, variantId, site, router.asPath, prevPath, path, state]);

This snippet of code can be added where the engage library is initialized so this problem is solved for all pages.

There is another problem again because of SSG and is related to experiences and experiments in Personalize. Every time the site loads, Personalize triggers the experiences and experiments that need to be shown in your site, but, again, as the layout doesn't reloads, Personalize doesn’t trigger neither the experiences nor experiments.

To solve this problem Engage has a function called triggerExperiences() which triggers all the experiences and experiments. This can also be added to the last snippet so them are triggered in all pages. In our case, we just have an experiment in the home page, so we validate that to trigger them.

useEffect(() => {
  if (pageState !== LayoutServicePageState.Normal || !route?.itemId) {
    return;
  }
  // Update prevPath with the previous path value
  setPrevPath(router.asPath);
  // Review if path has changed
  if (prevPath !== path) {
    // If it is the home page and the library is loaded, trigger experiences
    if (
      path === '/' &&
      window.Engage !== undefined &&
      window.Engage.triggerExperiences !== undefined
    ) {
      window.Engage.triggerExperiences();
    }
    const language = 'EN';
    const path = window.location.pathname.toLocaleLowerCase();
    const channel = 'WEB';
    window.engage.pageView({
      channel,
      currency: 'USD',
      pointOfSale: process.env.NEXT_PUBLIC_CDP_POINTOFSALE as string,
      page: path,
      language,
    });
    setPath(router.asPath);
  }
}, [pageState, route, variantId, site, router.asPath, prevPath, path, state]);