Skip to main content

The Next.js Personalize add-on

Abstract

Learn about the add-on that enables Next.js applications to get and render personalized page variants from XM Cloud.

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 you create a new project in XM Cloud using a Starter Kit. You can also add it using the JSS initializer.

This add-on includes:

  • A Next.js Middleware plugin.

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

  • A Page Props Factory plugin.

  • A Point of Sale (POS) resolver. In XM Cloud, the POS is referred to as Site identifier.

  • Additional environment variables for configuration.

Note

The Next.js Personalize add-on is only one piece of XM Cloud Embedded Personalization. You must use other tools in the suite to accomplish other tasks.

Personalization starts with a visitor page request.

The following diagram shows a generic visitor request flow when using the Next.js Personalize add-on.

Sequence/interaction diagram for the visitor request flow.

The middleware attempts to identify the personalized page variant to display based on the request/user context. Assuming 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.

The Personalize add-on uses a rewrite path to identify personalized page variants.

The rewrite path is:

The JSS Next.js SDK and Next.js Personalize add-on encapsulate the logic for these processes so that you do not have to manipulate this path directly. However, it is 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.

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.

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

NEXT_PUBLIC_CDP_TARGET_URL

Required.

A CDP target URL.

Used in personalization middleware and page view events.

Default: (none)

Example values:

  • https://api-engage-eu.sitecorecloud.io

  • https://api-engage-us.sitecorecloud.io

  • https://api-engage-ap.sitecorecloud.io

NEXT_PUBLIC_CDP_CLIENT_KEY

Required.

The CDP client key.

Used in personalization middleware and page view events.

Default: (none)

Example value: pqsPERS3lw12v5a9rrHPW1c4hET73GxQ

NEXT_PUBLIC_CDP_POINTOFSALE

Required.

A string or a map of locales and strings.

Used in personalization middleware and page view events.

Default: (none)

Single value example: example.com.

Locales map example:

{"en": "example.com", "da": "example.com/da"}

PERSONALIZE_MIDDLEWARE_CDP_TIMEOUT

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: 250

PERSONALIZE_MIDDLEWARE_EDGE_TIMEOUT

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: 250

Note

To obtain the NEXT_PUBLIC_CDP_TARGET_URL and NEXT_PUBLIC_CDP_CLIENT_KEY, make a request to Sitecore Support for XM Cloud Personalize Environment Variables. Include the site name in your request.

You can find the value for the NEXT_PUBLIC_CDP_POINTOFSALE in your SXA site definition, in the Point of sale field. You must add points of sale to Site identifiers to use them in analytics.

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 Starter Kit.