How to Diagnose Why Sitecore Personalize Might Not Be Working

Four quick issues you can look for when using Sitecore JSS 21.5

April 15, 2024

By David Austin

Recently, while setting up an environment for enabling a Web Experience from Sitecore Personalize to show up on a page, we noticed, that nothing happened. We did get it setup and I want to share the four places we found that could cause complications when enabling a Sitecore Personalize Web Experience or other Experiment.

1. CDP Not Initialized

Might seem obvious, but it isn’t. In order to have Sitecore Personalize work on your site, you do in-fact need Sitecore CDP installed and enabled on your site. For most out-of-the-box XM Cloud sites, at least if you’re pulling from recent Foundation Templates, will contain a CdpPageViewcomponent.

The component can be found inside your project here:

<XM Cloud Project>/src/<rendering>/src/components/CdpPageView.tsx

It is added to each page view the Scripts component which is located here:

<XM Cloud Project>/src/<rendering>/src/Scripts.tsx

Inside the Scripts.tsx file you’ll see how it references CdpPageView:

import CdpPageView from 'components/CdpPageView';

const Scripts = (): JSX.Element => { return ( <> <CdpPageView /> </> ); };

export default Scripts;

During the course of development it is not uncommon for a developer to comment out the <CdpPageView /> component because without the Client Key and CDP Endpoint environment variables, it produces an error.

Inside of CdpPageView.tsx you’ll find the initialization configuration. Two values, while the code might look find, might result in different values on the front-end.

const pointOfSale = PosResolver.resolve(site, language);
const engage = await init({
  clientKey: process.env.NEXT_PUBLIC_CDP_CLIENT_KEY || '',
  targetURL: process.env.NEXT_PUBLIC_CDP_TARGET_URL || '',
  // Replace with the top level cookie domain of the website that is being integrated e.g ".example.com" and not "www.example.com"
  cookieDomain: window.location.hostname.replace(/^www\./, ''),
  // Cookie may be created in personalize middleware (server), but if not we should create it here
  forceServerCookieMode: false,
});

Personalize here is obtained the Site Grouping Site item. Scroll down until you locate the Settings section and under Point of Sale add it as below. Left value is the language, right value is the name of the Point of Sale.

Screenshot of a content management system settings panel with various configuration options.

3. Personalize Not Enabled

When it comes to Sitecore Personalize specifically that Engage initialization above needs to be expanded upon. You will need to add in:

  cookieExpiryDays: 365,
  includeUTMParameters: true,
  webPersonalization: true,

Now, if you are not utilizing UTM Parameters then set that to false and adjust your cookie expiry accordingly. The most important attribute however is webPersonalization. Without this set to true Sitecore Personalize will NOT function.

4. Sitecore Engage Not Correct Version

It might be something you wouldn’t think you’d need to check but if you started your project prior to October 2023, there’s a chance your Sitecore XM Cloud Foundation project contained the old version for Sitecore Engage. You can see below this actually was updated only in October. You should have at minimum @sitecore/engage set to 1.4+. I mention this because this is what actually stumped me this time.

A code diff image highlighting updates to software dependencies in a project's configuration file.

How to Validate

When you are thinking you’ve solved your issue, you can load up your site that you have CDP & Personalize running on and in the URL append the following:

?bxQATool=true

After you hit Enter the page will load and it may take a moment but you should see this icon on the left.

Close-up of a cursor interacting with a marketing graphic of a burger with fiery effects.

Clicking it will reveal the full tool and will display any and all additional errors you may have.

A web tool interface displaying a quality assurance checklist for a burger advertisement.



Image of Fishtank employee David Austin

David Austin

Development Team Lead | Sitecore Technology MVP x 3

David is a decorated Development Team Lead with Sitecore Technology MVP and Coveo MVP awards, as well as Sitecore CDP & Personalize Certified. He's worked in IT for 25 years; everything ranging from Developer to Business Analyst to Group Lead helping manage everything from Intranet and Internet sites to facility management and application support. David is a dedicated family man who loves to spend time with his girls. He's also an avid photographer and loves to explore new places.