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 assumes that you:
-
Have collected the required details about your Sitecore CDP instance.
-
Have a React app to integrate.
This walkthrough describes how to:
-
Install and initialize
@sitecore/engage
. -
Send your first VIEW event.
-
Verify that Sitecore CDP captured your VIEW event.
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:
RequestResponsenpm install @sitecore/engage
-
In your code editor, open the root folder of your React app.
-
In the
src
folder, create a file calledengage.js
. -
In
engage.js
, paste the following code:RequestResponseimport { 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: false /* boolean or object. See Settings object for all options. Default: false */ }); 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 CDP instance.
This script:
-
Creates a context for Engage called
EngageContext
and a provider component calledEngageProvider
. -
In
EngageProvider
, 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 using
EngageProvider
. -
Exports the
useEngage
hook, which will allow you to easily call Engage functions in your app.
-
-
In
index.js
, wrap your app insideEngageProvider
.EngageProvider
will render your app, making all the Engage functionality available to the entire app:RequestResponseimport { 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, typeEngage;
. 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 CDP. 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 theApp
function, with theuseEngage
hook, call theengage.pageView()
function to send VIEW event data:RequestResponseimport { 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 CDP > Guests > Search field:"); console.log("bid:", 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 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 web browser, reload your app. When the webpage loads, the VIEW event triggers and the event data is sent.
Verify that Sitecore CDP captured your VIEW event
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.