Integrate a React app using the Engage SDK package

This topic explains how to integrate your React app using the Engage SDK package.

This walkthrough describes how to:

Install and initialize @sitecore/engage.
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 React app to integrate.

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 React app.
Install the Engage SDK by running the following command:
npm install @sitecore/engage
In your code editor, open the root folder of your React app.
In the src folder, create a file called engage.js.

In engage.js, paste the following code:

import { createContext, useContext, useState, useEffect, useCallback } from "react";
import { init } from "@sitecore/engage";

const EngageContext = createContext();

function EngageProvider({ children }) {
  const [engage, setEngage] = useState({});

  const loadEngage = useCallback(async () => {
    const 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. */
    });

    setEngage(engage);
  }, []);

  useEffect(() => {
    loadEngage();
  }, [loadEngage]);

  return <EngageContext.Provider value={engage}>{children}</EngageContext.Provider>;
}

function useEngage() {
  const engage = useContext(EngageContext);
  return engage;
}

export { EngageProvider, useEngage };

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:

Creates a context for Engage called EngageContext and a provider component called EngageProvider.
In EngageProvider, 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 using EngageProvider.
Exports the useEngage hook, which will allow you to easily call Engage functions in your app.

In index.js, wrap your app inside EngageProvider. EngageProvider will render your app, making all the Engage functionality available to the entire app:

import { EngageProvider } from "./engage";

const root = ReactDOM.createRoot(document.getElementById("root"));
root.render(
  <React.StrictMode>
    <EngageProvider>
      <App />
    </EngageProvider>
  </React.StrictMode>
);

In your terminal, enter npm start to start your React app. In your web browser console, type Engage;. If an object returns, you have successfully initialized 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:

In App.js, in the App function, with the useEngage hook, call the engage.pageView() function to send VIEW event data:

import { useEffect, useCallback } from "react";
import { useEngage } from "./engage";

export default function App() {
  const engage = useEngage();

  const sendPageViewEvent = useCallback(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());
    }
  }, [engage]);

  useEffect(() => {
    if (Object.keys(engage).length !== 0) {
      sendPageViewEvent();
    }
  }, [engage, sendPageViewEvent]);

  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.

In your web browser, reload your 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!