Back Arrow
From the blog

Troubleshooting tracking and personalisation in Sitecore XM Cloud

One of the first things I tested in Sitecore XM Cloud was embedded tracking and personalisation capabilities. It has been really interesting to see what is available out-of-the-box, how much flexibility XM Cloud offers to marketing teams and what is required from developers to set it up.

Anna Gevel

Sitecore MVP

In this article we will talk about troubleshooting steps for situations when Sitecore XM Cloud tracking or personalisation is not working as expected. I have been working with Sitecore XP for many years so over time it became easy to find what is wrong in my setup. As XM Cloud applications are built on a new technology stack, investigating issues initially was a challenge. So I created this troubleshooting guide and hope that you will find it useful too.

Troubleshooting tracking

The first step is to ensure that your website is tracking visitors correctly as without it you will not be able to use personalisation reports. Navigate to the Analyze section on the XM Cloud portal. If you see the "No data available" message and empty charts across both Site insights and Page insights, it is a sign that tracking is not functioning as expected.

Missing tracking data

To troubleshoot, load your website in a browser, open the Development Tools panel and switch to the Network tab. Refresh the page and look for a POST request to the Personalize tracking API, it should look similar to this:

https://api-engage-eu.sitecorecloud.io/v1.2/events

If you do not see this request, ensure that the component \src\components\CdpPageView.tsx and the file \src\Scripts.tsx are included in your layout (by default it is \src\Layout.tsx), otherwise tracking will not work.

Additionally, check the browser console for any error messages. Here are potential reasons that could cause them:

  • Incorrect Site Identifier (or Point of Sale in CDP/Personalize terminology)
  • Incorrect Target URL
  • Content Security Policy headers block tracking requests

Make sure that your Site Identifiers and Target URL match those from the Developer Settings in XM Cloud and that Target URL is whitelisted in your security headers.

Rectifying these errors should restore tracking functionality and you will start seeing statistics and charts similar to these in the XM Cloud portal:

Analytics reports in Sitecore XM Cloud

Troubleshooting personalisation

Troubleshooting personalisation can't be done directly via browser simply because it is performed on the server side within your rendering host application. This is where debug-level logging can help us see what happens behind the scenes.

To enable debug-level logs for the rendering host add the following line to the .env file:

  • DEBUG=sitecore-jss:*
  • or DEBUG=sitecore-jss:personalize* to limit detailed logging to the Personalize middleware only

After this you will start seeing API request and response details for both the GraphQL API and Sitecore Personalize API, as well as additional debugging information:

Debug logs of the rendering host container

Handling common scenarios

1. Middleware is disabled

One of the common reasons why personalisation does not seem to be working is the "disable" function of Personalize middleware. This function defines logic and conditions for skipping personalisation.

If the function returns "true", you will see the following message in the log:

sitecore-jss:personalize skipped (personalize middleware is disabled)

By default, it returns "true" for the development environment so personalisation will not be triggered on your local machine.

Solution:

Open the file \src\lib\middleware\plugins\personalize.ts and update the function disabled. Remember to implement your own logic, for example cookie consent validation.

The function "disabled" of Personalize middleware

2. Timeouts

Timeouts for both GraphQL and Personalize API requests can occur in development environments with frequent codebase updates and application restarts. If there is a timeout error, you will easily see which API responds slower than the allowed threshold.

Log message for GraphQL API timeout:

sitecore-jss:personalize request: {url: 'http://cm/sitecore/api/graph/edge’,…} sitecore-jss:personalize response error: 'Request timed out, timeout of 400ms is exceeded'

Log message for Personalize API timeout:

sitecore-jss:personalize request: {url: 'https://api-engage-eu.sitecorecloud.io/v2/callFlows’,…} sitecore-jss:personalize request error:  [AbortError: Request timed out, timeout of 400ms is exceeded]

Solution:

Adjusting timeout thresholds in the .env file can resolve these issues. However, be cautious not to set them too high as it can slow down your application. To increase API request timeouts, change the following variables:

  • PERSONALIZE_MIDDLEWARE_CDP_TIMEOUT for Personalize API
  • PERSONALIZE_MIDDLEWARE_EDGE_TIMEOUT for GraphQL API

Default values are 400ms and depending on the development environment configuration, these requests may be require more time to respond.

3. Personalize info not found

This error occurs when an incorrect page route or language is requested. Basically, it means that the GraphQL API was not able to find the requested page and layout details for it. Here is the log message to identify it, usually it is followed by 404 page response:

sitecore-jss:personalize skipped (personalize info not found)

Solution:

Make sure that you request the correct page URL and correct language version.

4. No personalization configured

If no personalised variants are configured for the requested page, the "no personalization configured" message appears in the log. It means that the GraphQL API was able to find the page and its layout, but the layout does not contain any personalised page variants.

sitecore-jss:personalize skipped (no personalization configured)

Solution:

Verify that the page you are testing indeed contains personalised variants. If the requested page does not have any personalisation rules, then this message is expected and may not require any fixes.

5. Browser ID generation failed

The browser ID is used for identifying requests from the same visitors. If a browser ID has been previously generated, it is stored in a cookie and sent to the server with every page request.

However, if it is the very request without any cookies (or cookies have been cleared), then Personalize middleware will attempt to generate a new browser ID for the current request. If something goes wrong during browser ID generation, the following message will be written to the log:

sitecore-jss:personalize skipped (browser id generation failed)

Solution:

Ensure that the correct Site Identifier, Target URL and Clint Key are configured in the .env file as they are needed for browser ID generation.

6. No variant identified

When the Personalize middleware sends a request but fails to identify any matching audience for the current visitor, the "no variant identified" message appears:

sitecore-jss:personalize skipped (no variant identified)

Solution:

Double check that the personalisation rule is correct and does match your current visitor audience.

If you are not sure what is wrong with the rule, try simplifying it as much as possible to identify which part of it is not working as expected. For example, if a rule combines multiple conditions, consider testing each condition individually to find which one is failing.

7. Invalid variant

This scenario occurs when an audience is identified for the current visitor, but the Personalize middleware is unable to find corresponding page variant in the page layout. It can be caused by outdated page definitions or mismatches between environments.

sitecore-jss:personalize skipped (invalid variant)

Solution:

If there are mismatches between content in XM Cloud and audience definitions, save personalisation rules in XM Cloud to synchronise them with Personalize API.

If you are seeing this error in a local development environment and want to test personalisation there, consider copying content from the environment where these personalisation rules were created.

Other API errors

If you are seeing any other errors related to personalisation, pay attention to logged API requests and responses. For example, an incorrect CM hostname or API key would trigger an error.

In some cases in can be useful to grab request details from logs and try running it in a tool like Postman to see how it is executed and what it returns.

GraphQL API request:

sitecore-jss:personalize request: {    
url: 'http://cm/sitecore/api/graph/edge',    
headers: { sc_apikey: ‘...' },    
query: '\n query($siteName: String!, $language: String!, $itemPath: String!) {\n layout(site: $siteName, routePath: $itemPath, language: $language) {\n item {\n id\n version\n personalization {\n variantIds\n }\n }\n }\n }\n ',    
variables: { siteName: 'Test', itemPath: '/', language: 'en’ }
}

Personalize API request:

sitecore-jss:personalize request: {   
url: 'https://api-engage-eu.sitecorecloud.io/v2/callFlows',    
headers: { content-type: 'application/json’, user-agent: ‘...’ },   timeout: 10000,   
method: 'POST',   
body: '{"clientKey":“...","pointOfSale":"default","channel":"WEB", "browserId":“...","friendlyId":"embedded_77735a5b0ac9441caa5f00428e47500_en", "params":{"referrer":"about:client","utm":{"campaign":“test_campaign", "content":null,"medium":null,"source":null}}}'
}

Successful response

When debug-level logging is enabled, successful responses from GraphQL and Personalize APIs will be saved too. Examples of successful responses and their data format are shown below.

GraphQL API response:

sitecore-jss:personalize response: {    
layout: {       
   item: {          
      id: '77735A5b0AC9441CAA5f00428E47500’,          
      version: 1,          
      personalization: {             
         variantIds: [ '25026aae743c4de2a5f54effc47f5a5c', length: 1 ]    
      }       
   }    
}}

Personalize API response:

sitecore-jss:personalize response: {    
status: 200,    
statusText: 'OK’,    
headers: { ... },    
url: 'https://api-engage-eu.sitecorecloud.io/v2/callFlows’,    
redirected: false,    
data: { variantId: '25026aae743c4de2a5f54effc47f5a5c’ }  
}

Finally, if you see the following "Personalize middleware end" message, congratulations, your website returned some personalised content!

You can use the logged variant ID to make sure that correct audience was selected and the expected variant is displayed on the website:

sitecore-jss:personalize personalize middleware end: {    
rewritePath: '/_variantId_0dd7b00680be49c6815ca4d0793a36da/_site_Test/About’,    
browserId: '53bda419-2228-4a4b-a406-5e08a453f9e9’,    
headers: {    
   set-cookie: 'BID_{CDP_client_key}=53bda419-2228-4a4b-a406-5e08a453f9e9;
   ...,    
   x-middleware-cache: 'no-cache’,    
   x-middleware-rewrite: 'http://localhost:3000/ variantId0dd7b00680be49c6815ca4d0793a36da/_site_Test/About’,    
   x-sc-rewrite: '/_variantId_0dd7b00680be49c6815ca4d0793a36da/_site_Test/About’ 
}
Conclusion

Hopefully, this guide helped you to understand the common issues in XM Cloud tracking and personalisation, and you found ideas on how to approach and resolve them.

It's easy to start working with us. Just fill the brief or call us.

Find out more
White Arrow
From the blog
Related articles

Inspecting raw database data in Xperience by Kentico

Dmitry Bastron

This article is a cheat sheet to inspect what's going on with the imported data by Xperience by Kentico Migration Toolkit, resolve some CI/CD issues and on many other occasions!

Kentico

Learnings from using Sitecore ADM

Anna Bastron

Let's try to understand how the ADM module works, its limitations and tactics for optimising its performance.

Sitecore

Your last migration to Xperience by Kentico

Dmitry Bastron

The more mature Xperience by Kentico product becomes, the more often I hear "How can we migrate there?”

Kentico

5 Key Software Architecture Principles for Starting Your Next Project

Andrey Stepanov

In this article, we will touch on where to start designing the architecture and how to make sure that you don’t have to redo it during the process.

Architecture
Software development

Assessing Algorithm Complexity in C#: Memory and Time Examples

Anton Vorotyncev

Today, we will talk about assessing algorithm complexity and clearly demonstrate how this complexity affects the performance of the code.

.NET

Top 8 B2B Client Service Trends to Watch in 2024

Tatiana Golovacheva

The development market today feels like a race - each lap is quicker, and one wrong move can cost you. In this race, excellent client service can either add extra points or lead to a loss dot to high competition.

Customer Service
Client Service

8 Non-Obvious Vulnerabilities in E-Commerce Projects Built with NextJS

Dmitry Bastron

Ensuring security during development is crucial, especially as online and e-commerce services become more complex. To mitigate risks, we train developers in web security basics and regularly perform third-party penetration testing before launch.

Next.js
Development

How personalisation works in Sitecore XM Cloud

Anna Bastron

In my previous article, I shared a comprehensive troubleshooting guide for Sitecore XM Cloud tracking and personalisation. This article visualises what happens behind the scenes when you enable personalisation and tracking in your Sitecore XM Cloud applications.

Sitecore

Server and client components in Next.js: when, how and why?

Sergei Pestov

All the text and examples in this article refer to Next.js 13.4 and newer versions, in which React Server Components have gained stable status and became the recommended approach for developing applications using Next.js.

Next.js

How to properly measure code speed in .NET

Anton Vorotyncev

Imagine you have a solution to a problem or a task, and now you need to evaluate the optimality of this solution from a performance perspective.

.NET

Formalizing API Workflow in .NET Microservices

Artyom Chernenko

Let's talk about how to organize the interaction of microservices in a large, long-lived product, both synchronously and asynchronously.

.NET

Hidden Aspects of TypeScript and How to Resolve Them

Dmitry Berdnikov

We suggest using a special editor to immediately check each example while reading the article. This editor is convenient because you can switch the TypeScript version in it.

TypeScript

Mastering advanced tracking with Kentico Xperience

Dmitry Bastron

We will take you on a journey through a real-life scenario of implementing advanced tracking and analytics using Kentico Xperience 13 DXP.

Kentico
Devtools

Why is Kentico of such significance to us?

Anastasia Medvedeva

Kentico stands as one of our principal development tools, we believe it would be fitting to address why we opt to work with Kentico and why we allocate substantial time to cultivating our experts in this DXP.

Kentico

Where to start learning Sitecore - An interview with Sitecore MVP Anna Gevel

Anna Gevel

As a software development company, we at Byteminds truly believe that learning and sharing knowledge is one of the best ways of growing technical expertise.

Sitecore

Sitecore replatforming and upgrades

Anastasia Medvedeva

Our expertise spans full-scale builds and support to upgrades and replatforming.

Sitecore

How we improved page load speed for Next.js ecommerce website by 50%

Sergei Pestov

How to stop declining of the performance indicators of your ecommerce website and perform optimising page load performance.

Next.js

Sitecore integration with Azure Active Directory B2C

Dmitry Bastron

We would like to share our experience of integrating Sitecore 9.3 with the Azure AD B2C (Azure Active Directory Business to Consumer) user management system.

Sitecore
Azure

Activity logging with Xperience by Kentico

Dmitry Bastron

We'll dive into practical implementation in your Xperience by Kentico project. We'll guide you through setting up a custom activity type and show you how to log visitor activities effectively.

Kentico

Interesting features of devtools for QA

Egor Yaroslavcev

Chrome DevTools serves as a developer console, offering an array of in-browser tools for constructing and debugging websites and applications.

Devtools
QA

Kentico replatforming and upgrades

Anastasia Medvedeva

Since 2015, we've been harnessing Kentico's capabilities well beyond its core CMS functions.

Kentico

Umbraco replatforming and upgrades

Anastasia Medvedeva

Our team boasts several developers experienced in working with Umbraco, specialising in development, upgrading, and replatforming from other CMS to Umbraco.

Umbraco

Sitecore Personalize: tips & tricks for decision models and programmable nodes

Anna Gevel

We've collected various findings around decision models and programmable nodes working with Sitecore Personalize.

Sitecore

Fixed Price, Time & Materials, and Retainer: How to Choose the Right Agreement for Your Project with Us

Andrey Stepanov

We will explain how these agreements differ from one another and what projects they are suitable for.

Customer success

Enterprise projects: what does a developer need to know?

Fedor Kiselev

Let's talk about what enterprise development is, what nuance enterprise projects may have, and which skills you need to acquire to successfully work within the .NET stack.

Development

Headless CMS. Identifying Ideal Use Cases and Speeding Up Time-to-Market

Andrey Stepanov

All you need to know about Headless CMS. We also share the knowledge about benefits of Headless CMS, its pros and cons.

Headless CMS

Dynamic URL routing with Kontent.ai

We'll consider the top-to-bottom approach for modeling content relationships, as it is more user-friendly for content editors working in the Kontent.ai admin interface.

Kontent Ai
This website uses cookies. View Privacy Policy.