Personalization in JSS Next.js applications

Current version: 22.0

The Next.js XM Cloud 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 Events package in the Sitecore Cloud 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 elements for supporting personalization:

  • A Next.js Middleware plugin.

  • A React component for Page View events using the Sitecore Cloud SDK for JavaScript.

  • A Page Props Factory plugin.

  • Additional environment variables for configuration.

Note

The personalization tooling in the XM Cloud 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. When published, these variants are stored on the page layout data in Sitecore Experience Edge.

  • 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 when using the personalization implementation in the XM Cloud add-on.

Sequence/interaction diagram for the visitor request flow.

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 CDK Events implementation triggers Page View events.

Understanding the personalized rewrite path

The personalization implementation in the Next.js XM Cloud add-on uses a rewrite path to identify personalized page variants.

The rewrite path is:

The personalization implementation encapsulates 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:

RequestResponse

/_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 XM Cloud 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.

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.

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.

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.

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.

Environment variables

You use environment variables to configure personalization in a JSS Next.js app.

The following table lists the environment variables specific to the personalization functionality. You must populate all the required variables with values specific to your project/environment.

Variable

Description

Values

NEXT_PUBLIC_PERSONALIZE_SCOPE

Optional.

Unique page identifiers are used to run personalization flows and analytics. However, if pages are created through site serialization, identical page identifiers may exist across different XM Cloud environments.

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

embedded_{pageID}_{language}

After adding the PAGES_PERSONALIZE_SCOPE variable with a value of myEnv, for example, that ID is changed to:

RequestResponse

embedded_myEnv_{pageID}_{language}

PERSONALIZE_MIDDLEWARE_CDP_TIMEOUT

Optional.

Value is in milliseconds. It allows fine-tuning timeout for CDP calls within the personalization middleware. If the timeout is exceeded, the user sees the default page.

Default: 400

PERSONALIZE_MIDDLEWARE_EDGE_TIMEOUT

Optional.

The value is in milliseconds. This setting allows you to fine-tune the timeout for Experience Edge calls within the personalization middleware. If the timeout is exceeded, the user sees the default page.

Default: 400

Note

You must add points of sale to Site identifiers to use them in analytics.

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.

Do you have some feedback for us?

If you have suggestions for improving this article,