The Next.js Personalize add-on
The Next.js Personalize add-on includes an example setup for projects using XM Cloud Embedded Personalization. It uses Next.js Middleware architecture to enable personalization at the edge, combined with the Sitecore Engage SDK for Page View events in the browser.
This add-on is automatically included when creating a new XM Cloud project using a foundation template. You can also add it using the JSS initializer.
This add-on includes the following:
-
A Next.js Middleware plugin.
-
A React component for Page View events using the Sitecore Engage SDK.
-
A Page Props Factory plugin.
-
Point of Sale (POS) population for the default Site Resolver plugin. In XM Cloud, the POS is referred to as Site identifier.
-
Additional environment variables for configuration.
The Next.js Personalize add-on is only one piece of the embedded personalization feature of XM Cloud. You must use other tools in the suite to accomplish other tasks. For example:
-
Use XM Cloud Pages Personalize to create personalized page variants. These variants are stored on the page layout data in Sitecore Experience Edge when published.
-
Use XM Cloud Pages Analyze to view Page View events.
Architecture overview
Personalization starts with a visitor page request.
The following diagram shows a generic visitor request flow using the Next.js Personalize add-on.
The middleware tries to identify the personalized page variant to display based on the request/user context. If the middleware successfully identifies a page variant, it rewrites the path to the page variant path (personalized rewrite path).
The Next.js app parses the personalized rewrite path to get the variant. It then manipulates the layout and displays the correct personalized page to the visitor.
In the browser, the Sitecore Engage SDK triggers Page View events.
Understanding the personalized rewrite path
The Personalize add-on uses a rewrite path to identify personalized page variants.
The rewrite path is:
-
Set by Personalize Middleware to the identified page variant.
-
Read by the Next.js app to manipulate the layout and feed to Page View events.
-
Used to enable static generation for personalized page variants.
The JSS Next.js SDK and Next.js Personalize add-on encapsulate the logic for these processes so that you don't have to manipulate this path directly. However, it's helpful to understand in case of troubleshooting or customizations.
The structure of the personalized rewrite path is:
/_variantId_<variantId>/<path>For example, a page with the path /foo/bar and the personalized variant 1234 , is represented by the path /_variantId_1234/foo/bar.
APIs
The Personalize add-on uses the following code artifacts to render personalized page variants:
PersonalizeMiddleware
The PersonalizeMiddleware is a Next.js middleware handler that enables Sitecore personalization of pages.
The middleware:
-
Makes a call to the Sitecore Experience Edge endpoint to get the personalization information about the page, including variants.
-
Calls the Sitecore CDP endpoint with request/user context to determine the page variant to display based on the response.
-
Rewrites the response to the specific page variant using the personalized rewrite path.
For additional information, see the reference documentation.
normalizePersonalizedRewrite
The normalizePersonalizedRewrite function removes personalization data from a personalized rewrite path so that layout data can be appropriately retrieved. The function is used by the Page Props Factory extractPath function defined in the src\lib\page-props-factory\extract-path.ts file of a Next.js application with the Personalize add-on installed.
For additional information, see the reference documentation.
getPersonalizedRewriteData
The getPersonalizedRewriteData function extracts personalization data (variantId) from a personalized rewrite path. The Page Props Factory plugin for personalization, defined in the src/lib/papge-props-factory/plugins/personalize.ts file, passes the data to the personalizeLayout function.
For additional information, see the reference documentation.
personalizeLayout
The personalizeLayout function modifies layout data to use a specific variant based on the provided variantId parameter instead of the default layout. The function also sets the variantId property on the Sitecore context.
For additional information, see the reference documentation.
CdpHelper
The CdpHelper class provides the getPageVariantId function that gets the page variant identifier in the format required for the pageVariantId parameter of a Page View event.
For additional information, see the reference documentation.
Environment variables
You use environment variables to configure the Personalize add-on.
The following table lists the environment variables specific to the Next.js personalize add-on. You must populate all the required variables with values specific to your project/environment.
|
Variable |
Description |
Values |
|---|---|---|
|
|
Required. A CDP target URL. Used in personalization middleware and page view events. |
Default: (none) Example values:
|
|
|
Required. The CDP client key. Used in personalization middleware and page view events. |
Default: (none) Example value: pqsPERS3lw12v5a9rrHPW1c4hET73GxQ |
|
|
Required. A string or a map of locales and strings. Used in personalization middleware and page view events. When using the Next.js Multisite add-on, the value of the variable represents the Point of Sale (POS) configuration of the default/configured site. When configuring multiple sites (for specific hostnames), the application uses the automatically-fetched site information containing the POS configuration. |
Default: (none) Single value example: Locales map example: RequestResponse |
|
|
Optional. In XM Cloud Personalize, unique page identifiers are used to run personalization flows and analytics. In some cases, identical page identifiers exist across different XM Cloud environments, for example, if pages are created through site serialization. Use this variable to Isolate personalization data between such XM Cloud environments. It creates a unique page personalization identifier for each environment. |
Default: (none) If you don't use the variable, the default structure for identifying a personalized page is: RequestResponse After adding the RequestResponse |
|
|
Optional. Value is in milliseconds. Provides the ability to fine-tune timeout for CDP calls within the personalization middleware. If the timeout is exceeded, the user sees the default page. |
Default: 400 |
|
|
Optional. Value is in milliseconds. Provides the ability to fine-tune timeout for Experience Edge calls within the personalization middleware. If the timeout is exceeded, the user sees the default page. |
Default: 400 |
You can find the NEXT_PUBLIC_CDP_POINTOFSALE, NEXT_PUBLIC_CDP_TARGET_URL, and NEXT_PUBLIC_CDP_CLIENT_KEY values in your XM Cloud Site Settings under the Developer Settings tab.
You must add points of sale to Site identifiers to use them in analytics.
Limitations
The Personalize add-on has the following limitations:
-
The Next.js Personalize add-on is only compatible with XM Cloud.
-
Automatic provisioning of CDP tenants and Point of Sale management is only possible if you create a new project in XM Cloud using a foundation template.