Skip to main content

Walkthrough: Configuring the Next.js Personalize add-on

Abstract

Tips for excluding a route from personalization, changing the cookie domain or currency, and enabling/disabling personalization features.

When you create a Next.js application and include the Next.js Personalize add-on, or you use an XM Cloud Stater Kit, the add-on is preconfigured with working default values, but you might have to adjust the default configuration to fit your requirements.

This walkthrough describes how to:

  • Configure the required environment variables.

  • Exclude routes from personalization.

  • Change the cookie domain.

  • Change the Page View Events configuration.

  • Enable or disable the Personalize middleware and Page View event tracking.

  • Enable static generation for personalized variants.

You must use environment variables to configure the Personalize add-on.

To configure the Personalize add-on:

  • Provide the values for the following environment variables used in personalization middleware and page view events:

    • NEXT_PUBLIC_CDP_TARGET_URL.

    • NEXT_PUBLIC_CDP_CLIENT_KEY.

    • NEXT_PUBLIC_CDP_POINTOFSALE.

The Personalize middleware excludes some routes from personalization by default, such as files, Next.js API routes, Sitecore API calls, and Next.js service calls.

Because the Personalize middleware runs on every request, you can improve the performance of your application by excluding additional routes to prevent the middleware from requesting the page variants for those routes.

To exclude additional routes:

  • In the root directory of the Next.js application, in the src\lib\middleware\plugins\personalize.ts file, update the excludeRoute function to exclude the desired path name.

    For example:

    excludeRoute: (pathname: string) => {
      if (pathname.startsWith('/products')) {
        return true;
      }
      return false;
    }

The cookie domain is set by default in the CDP Page View component to a transformed value of the current browser location host (window.location.host.replace(/^www\./, '')). You can replace the value in the file with a specific domain or an environment variable.

The CDP Page View component is defined in the src\components\CdpPageView.tsx file.

Assume you have defined an environment variable for your application as follows:

NEXT_PUBLIC_COOKIE_DOMAIN=.mysite.com

To change the cookie domain configuration:

  • In the root directory of the Next.js application, in the src\components\CdpPageView.tsx file, in Sitecore Engage SDK client init function (the engage constant), replace the cookieDomain value:

    const engage = await init({
        clientKey: process.env.NEXT_PUBLIC_CDP_CLIENT_KEY || '',
        targetURL: process.env.NEXT_PUBLIC_CDP_TARGET_URL || '',
        cookieDomain: process.env.NEXT_PUBLIC_COOKIE_DOMAIN || window.location.host.replace(/^www\./, ''),
        forceServerCookieMode: false,
    });

The Page View event configured in the CDP Page View component comes with a default configuration, such as the WEB channel and USD currency.

You can replace the default values with hard-coded values or environment variables.

For example, to change the currency settings for the Page View events:

  • In the root directory of the Next.js application, in the src\components\CdpPageView.tsx file, in the Page View event configuration, change the currency code to EUR. For example:

    engage.pageView({
          channel: 'WEB',
          currency: 'EUR',
          pos: pointOfSale,
          page,
          pageVariantId,
          language,
    });

The Next.js Personalize add-on comes with both the Personalize middleware and Page View events enabled by default to reduce the configuration requirements during the development phase of a project.

In production, personalization and event tracking likely depend on visitor consent and the resulting consent cookie.

To control personalization and/or event tracking based on visitor consent:

  1. Implement your cookie consent management solution of choice.

  2. Modify the enable/disable hooks for personalization and/or event tracking based on visitor consent and the resulting cookie.

    The enable/disable hooks are available in the following files:

    • In the src\lib\middleware\plugins\personalize.ts file - the disabled option for the Personalize middleware.

    • In the src\components\CdpPageView.tsx file - the disabled function in the CDP Page View component.

Build-time static generation of personalized page variants is disabled by default for build performance considerations, but you can enable static generation.

To enable static generation of personalized page variants at build-time:

  • In the root directory of the Next.js application, in the src\lib\sitemap-fetcher\plugins\graphql-sitemap-service.ts file, edit the configuration of the GraphQL Sitemap Service, setting the includePersonalizedRoutes option to true. For example:

    this._graphqlSitemapService = new GraphQLSitemapService({
      endpoint: config.graphQLEndpoint,
      apiKey: config.sitecoreApiKey,
      siteName: config.jssAppName,
      includePersonalizedRoutes: true,
    });