Integrate a Next app using the Engage SDK package (client-set cookies)

Note

If your organization has a JSS Next.js application hosted on Sitecore XM Cloud, implement Sitecore CDP-related functionality on your XM Cloud site using the Sitecore Cloud SDK instead. See also a comparison of the Cloud SDK and the Engage SDK.

This topic explains how to integrate your Next.js app using the Engage SDK package. In this walkthrough, you'll use client-set cookies.

This walkthrough describes how to:

Install and initialize @sitecore/engage.
Send your first VIEW event.
Verify that Sitecore CDP captured your VIEW event.

Before you begin

Collect the required details about your Sitecore CDP 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

The first step to integrating your app is to install and initialize the @sitecore/engage package.

To install and initialize the package:

In your terminal, open the root folder of your Next.js app.
Install the Engage SDK by running the following command:
RequestResponse
```
npm install @sitecore/engage
```
In your code editor, open the root folder of your Next.js app.
Depending on your router type:
- If using the Pages Router - in the pages/api folder, create a file called engage.js.
- If using the App Router - in the app folder, create a subfolder called _api. Then, in the _api folder, create a file called engage.js.

In engage.js, paste the following code:

RequestResponse

import { init } from "@sitecore/engage";

let engage;

const loadEngage = async () => {
  engage = await init({
    clientKey: "<client_key_PLACEHOLDER>",
    targetURL: "<stream_api_target_endpoint_PLACEHOLDER>",
    pointOfSale: "<point_of_sale_PLACEHOLDER>",
    cookieDomain: "<cookie_domain_PLACEHOLDER>",
    cookieExpiryDays: 365,
    forceServerCookieMode: false,
    includeUTMParameters: true,
    webPersonalization: false /* boolean or object. See Settings object for all options. Default: false */
  });
};

loadEngage();
export { engage };

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

This script:

Imports the init() function from the @sitecore/engage package.
Asynchronously loads the Engage API using details about your Sitecore CDP instance and sets cookies from the client.
Exports your instance of the Engage API as a variable called engage.

To import modules:
- If using the Pages Router - in the pages folder, in the index.js file, import useEffect from React and engage from engage.js:
  RequestResponse
  import { useEffect } from "react"; import { engage } from "./api/engage.js";
- If using the App Router - in the app folder, in the page.js file, import useEffect from React and engage from _api/engage. Also, add the "use client" directive at the top of of the file, above all the imports:
  RequestResponse
  "use client"; import { useEffect } from "react"; import { engage } from "./_api/engage";

Send your first VIEW event

After you have installed and initialized the @sitecore/engage package, you collect and send data to Sitecore CDP. You'll send a VIEW event because the VIEW event triggers every time your webpage loads.

To send a VIEW event:

To send VIEW event data:

If using the Pages Router - in the index.js file, in the Home function, call the engage.pageView() function:

RequestResponse

export default function Home() {

  // Send VIEW event ->
  useEffect(() => {
    if (engage !== undefined) {
      sendPageViewEvent();
    };
  }, []);

  const sendPageViewEvent = async () => {
    const response = await engage.pageView({
      channel: "<channel_PLACEHOLDER>",
      currency: "<currency_PLACEHOLDER>"
    });

    // For testing and debugging purposes only
    if (response) {
    console.log("Copy-paste the following line into Sitecore CDP > Guests > Search field:");
      console.log("bid:", engage.getBrowserId());
    };
  };
  // <- Send VIEW event

  return (<></>)
}

If using the App Router - in the page.js file, in the Home function, call the engage.pageView() function:

RequestResponse

export default function Home() {

  // Send VIEW event ->
  useEffect(() => {
    if (engage !== undefined) {
      sendPageViewEvent();
    };
  }, []);

  const sendPageViewEvent = async () => {
    const response = await engage.pageView({
      channel: "<channel_PLACEHOLDER>",
      currency: "<currency_PLACEHOLDER>"
    });

    // For testing and debugging purposes only
    if (response) {
    console.log("Copy-paste the following line into Sitecore CDP > Guests > Search field:");
      console.log("bid:", engage.getBrowserId());
    };
  };
  // <- Send VIEW event

  return (<></>)
}

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

This script creates a VIEW event object and sends the event data to Sitecore CDP immediately after the component renders for the first time. It also logs the browser ID to the console. You'll use the browser ID in the next procedure to find the VIEW event in Sitecore CDP.

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 CDP captured your VIEW event

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

To verify that Sitecore CDP captured your VIEW event:

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

bid: a38b230c-11eb-4cf9-8d5d-274e9f344925

Tip

This text consists of the bid: prefix plus a browser ID.

In Sitecore CDP, to find your users by the browser ID, always use the bid: prefix plus the browser ID notation. For example: bid: a38b230c-11eb-4cf9-8d5d-274e9f344925
Copy the text.
In Sitecore CDP, click Guests. Paste the copied text into the Search field.

An anonymous guest displays.

This guest is you loading your app just a minute ago. Next, you find the VIEW event associated with this guest.
Click the guest. The guest profile displays.
On the guest profile page, click Event viewer. A list of events associated with this guest displays. The list contains a VIEW event. This is the event that was triggered in the previous procedure.

Next steps

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

Do you have some feedback for us?

If you have suggestions for improving this article,