Integrate a Next.js app using the Engage SDK package (server-set cookies)

This topic explains how to integrate your Next.js app using the Engage SDK package. In this walkthrough, you'll use server-set cookies. We assume that you are using the src folder, but you don't have to.

This walkthrough describes how to:

Install and initialize @sitecore/engage on the server side.
Initialize @sitecore/engage on the client side.
Send your first VIEW event.
Verify that Sitecore Personalize captured your VIEW event.

Before you begin

Collect the required details about your Sitecore Personalize instance.
Have a Next.js app to integrate. This walkthrough was tested on Next.js versions 12, 13, and 14.2.5, both for the Pages Router and the App Router.

Install and initialize @sitecore/engage on the server side

The first step to integrating your app is to install and initialize the @sitecore/engage package in your web server. This step involves setting cookies from the server and sending them to the client.

To install and initialize the package on the server side:

In your terminal, open the root folder of your Next.js app.
Install the Engage SDK by running the following command:
npm install @sitecore/engage
In your code editor, open the root folder of your Next.js app.
In the src folder, create a file called middleware.js.

In middleware.js paste the following code:

import { NextResponse } from 'next/server';
import { initServer } from '@sitecore/engage';

export async function middleware(request) {
  const response = NextResponse.next();

  try {
    const engageSettings = {
      clientKey: "<client_key_PLACEHOLDER>",
      targetURL: "<stream_api_target_endpoint_PLACEHOLDER>",
      pointOfSale: "<point_of_sale_PLACEHOLDER>",
      cookieDomain: "<cookie_domain_PLACEHOLDER>",
      cookieExpiryDays: 365,
      forceServerCookieMode: true
    };

    const engageServer = initServer(engageSettings);
    await engageServer.handleCookie(request, response);
  } catch (error) {
    console.error(error);
  }

  return response;
};

Replace the placeholder values with the required details from your Sitecore Personalize instance.

Content Security Policy (CSP)

To ensure that the Engage SDK script loads, you might have to add the following to your Content Security Policy (CSP):

Your Stream API target endpoint.
https://d1mj578wat5n4o.cloudfront.net
If you run web personalization and your environment is AP Region, EU Region, or US Region:

https://d35vb5cccm4xzp.cloudfront.net
If you run web personalization and your environment is JP Region:

https://d2ez8k04aaol9g.cloudfront.net

This script:

Initializes the Engage SDK in a middleware function on the server using the initServer() function.
Collects the details about your Sitecore Personalize instance and cookie settings in the engageSettings object, and passes the object to the EngageServer.handleEngageCookie() function.
Sets cookies from the server.

Initialize `@sitecore/engage` on the client side

After you have installed and initialized the @sitecore/engage package in your web server, you initialize the package on the client side. This step involves receiving cookies from the server and storing them in the web browser.

To initialize the package on the client side:

Depending on your router type:
- If using the Pages Router - in the pages folder, in the index.js file, import useEffect from React and init from @sitecore/engage:
  import { useEffect } from "react"; import { init } from "@sitecore/engage";
- If using the App Router - in the app folder, in the page.js file, import useEffect from React and init from @sitecore/engage. Also, add the "use client" directive at the top of of the file, above all the imports:
  "use client"; import { useEffect } from "react"; import { init } from "@sitecore/engage";

Above the Home() function, create an object called engageSettings:

const engageSettings = {
  clientKey: "<client_key_PLACEHOLDER>",
  targetURL: "<stream_api_target_endpoint_PLACEHOLDER>",
  pointOfSale: "<point_of_sale_PLACEHOLDER>",
  forceServerCookieMode: true,
  includeUTMParameters: true,
  webPersonalization: true /* boolean or object. See Settings object for all options. */
};

Replace the placeholder values with the required details from your Sitecore Personalize instance.

In the Home() function, create an empty, asynchronous function loadEngage(), then call loadEngage() in an Effect Hook. You should use the Effect Hook because the window object has to be present before you load the Engage API. In the next procedure, you'll update the code inside loadEngage() to load the Engage API and start sending VIEW events.

export default function Home() {
  const loadEngage = async () => {
    // Load Engage API
    // Send VIEW events
  };
    
  useEffect(() => {
    loadEngage();
  }, []);

  return (<></>)
};

Send your first VIEW event

Next, you update the code inside the loadEngage() function to start collecting and sending data to Sitecore Personalize. You'll send a VIEW event because the VIEW event triggers every time your webpage loads.

To send a VIEW event:

In the loadEngage() function, load the Engage API by passing engageSettings to the init() function. The init() function is asynchronous, so you must await the return value.
const loadEngage = async () => { // Load Engage API const engage = await init(engageSettings); // Send VIEW events };
In production, you should call the init() function once, then share it across the app using the state management solution of your choice, for example, React Context or Redux.

In the loadEngage() function, after you load the Engage API, call the engage.pageView() function to send VIEW event data:

const loadEngage = async () => {
  // Load Engage API
  const engage = await init(engageSettings);  

  // Send VIEW events
  engage.pageView({
    channel: "<channel_PLACEHOLDER>",
    currency: "<currency_PLACEHOLDER>"
  });
};

Replace the placeholder values with the event details specific to your organization.

In the loadEngage() function, below the engage.pageView() function, for testing and debugging purposes only, log the browser ID to the console:

const loadEngage = async () => {
  // Load Engage API
  // ...

  // Send VIEW events
  // ...

  // For testing and debugging purposes only
  console.log("Copy-paste the following line into Sitecore Personalize > Developer center > Event viewer > Search field:");
  console.log(engage.getBrowserId());
};

You'll use the browser ID in the next procedure to find the VIEW event in Sitecore Personalize.

In your terminal, enter npm run dev to start your Next.js app. When the webpage loads, the VIEW event triggers and the event data is sent.

Verify that Sitecore Personalize captured your VIEW event

After you have sent a VIEW event, you log in to Sitecore Personalize and find the event.

To verify that Sitecore Personalize captured your VIEW event:

In your web browser's console, find a text similar to:

a38b230c-11eb-4cf9-8d5d-274e9f344925
Copy the text.
In Sitecore Personalize, click Developer center > Event viewer, then in the search dropdown, select Browser ID and paste the copied text into the search field. A list of events associated with this guest displays. The list contains a VIEW event. This is the event that was triggered in a previous procedure.

Note

If you have both Sitecore CDP and Sitecore Personalize, you can find the data in Guests.

Next steps

You've now successfully integrated your app with Sitecore Personalize. You sent an event from your app and verified that Sitecore Personalize captures data about your users in real time.

If you have suggestions for improving this article, let us know!

Integrate a Next.js app using the Engage SDK package (server-set cookies)

Install and initialize @sitecore/engage on the server side

Initialize @sitecore/engage on the client side

Send your first VIEW event

Verify that Sitecore Personalize captured your VIEW event

Next steps

Initialize `@sitecore/engage` on the client side