Enabling Sitecore Personalize Web Experiences on XM Cloud

Hello folks, welcome back to my blog. Today, I want to discuss creating Web Experiences (Sitecore Personalize) with XM Cloud. Out of the box, running a web experience/experiment with your XM Cloud tenant requires additional configuration with your rendering host. Even though this topic may be brief, I believe it's worth outlining the necessary steps.

Cloud SDK vs Engage SDK

With XM Cloud specifically, it’s important to talk about the recent release of JSS 21.6 (https://doc.sitecore.com/xmc/en/developers/jss/216/jss-xmc/index-en.html). In this version, Sitecore introduced a better developer experience which included the simplification of the usage of SDKs across products. With this, the Engage SDK was replaced by the Cloud SDK and there are some important items to discuss with the Cloud SDK at the time of writing this article. The biggest item to highlight is that the Cloud SDK doesn’t currently support the usage of Web Experiences in Personalize. That doesn’t mean you can’t personalize, it just means you must use only Conditions to personalize. Another option is to create full-stack interactive experiences. The latter I’ll likely cover in a future topic. Custom conditions are not always the answer, even though they work very well with XM Cloud Pages, it can however be very tricky to create advanced personalization scenarios with conditions. Or you might want to create a decision model, in those cases you will need to either wait for support for Web Experiences with the Cloud SDK or implement some form of full-stack interactive experiences.

For today’s blog post, I am going to assume you are using a version of JSS before 21.6, and therefore using the Engage SDK. With the Engage SDK with an XM Cloud website, it’s quite easy to enable web experiences/experiments with your XM Cloud tenant.

Modifications Needed

To enable web experiences or experiments, you need to adjust the configuration in your rendering host. If you're using multiple rendering hosts from different file systems (like a mono repo), you should apply these changes to all file systems where you want to enable web experiences.

This guide assumes you're using the latest version of the Engage SDK and that you initiated your rendering host using the Foundation head repo. You can find it here: https://github.com/sitecorelabs/xmcloud-foundation-head.

The primary change required pertains to our Engage SDK initialization. Two configuration settings are necessary to ensure that web experiences function correctly on our XM Cloud rendering host.

• pointOfSale - This was optional before, but is now required, luckily this setting is already set and configured to the correct value using the PosResolver.resolve().
• webPersonalization - This is a boolean value, that to enable web experiences in the browser, it needs to be set to true.

Let's examine the required changes in the code. These modifications apply to CdpPageView.tsx, specifically within the createPageView function. Optionally, you could clone this file and reference it separately to minimize the risk of overwriting your specific configuration during JSS updates. Alternatively, consider passing the webPersonalization parameter as an environment variable.

1const createPageView = async(page: string, language: string, site: SiteInfo, pageVariantId: string) => 
2{
3	const pointOfSale = PosResolver.resolve(site, language);
4	const engage = await init({
5		clientKey: process.env.NEXT_PUBLIC_CDP_CLIENT_KEY || '',
6		targetURL: process.env.NEXT_PUBLIC_CDP_TARGET_URL || '',
7		cookieDomain: window.location.host.replace(/^www\./, ''),
8		forceServerCookieMode: false,
9		pointOfSale,
10		webPersonalization: true
11	});
12}

Highlighted above in red, are the additions that I’ve added to enable web experiences and experiments in XM Cloud. Make sure you’ve committed these changes and deployed these to the environments where you plan to run web personalization. Once everything has been deployed, you should be able to go into Sitecore Personalize, create a new “Web Experience” and then preview that experience and view that experience on your XM Cloud website. You can also see the QA tool at any point just by going to https://yourwebsite.com/?bxQATool=true.

And that’s pretty much it for this blog post and simple to achieve.