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

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:

1. In your terminal, open the root folder of your Next.js app.

2. Install the Engage SDK by running the following command:

   npm install @sitecore/engage

3. In your code editor, open the root folder of your Next.js app.

4. 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.

5. In engage.js, paste the following code:

   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: true /* boolean or object. See Settings object for all options. */
     });
   };
   
   loadEngage();
   export { engage };

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

   Cookie consent

   In production, only load the Engage SDK and set cookies if your site visitor grants consent. See also a code example to check if your site visitor accepts cookies.

   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:

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

6. 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:

     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:

     "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 Personalize. You'll send a VIEW event because the VIEW event triggers every time your webpage loads.

To send a VIEW event:

1. To send VIEW event data:

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

     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 Personalize > Developer center > Event viewer > Search field:");
           console.log(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:

     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 Personalize > Developer center > Event viewer > Search field:");
           console.log(engage.getBrowserId());
         };
       };
       // <- Send VIEW event
     
       return (<></>)
     }

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

   This script creates a VIEW event object and sends the event data to Sitecore Personalize 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 Personalize.

2. 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:

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

   a38b230c-11eb-4cf9-8d5d-274e9f344925​

2. Copy the text.

3. 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.

Next, you can:

• Send other behavioral data, for example, an IDENTITY event or a custom event.
• Send transactional data as the user interacts with products and shopping carts on your site.
• Run experiences and experiments.