Sitecore Engage
© Sitecore Corporation A/S. All rights reserved. Sitecore© is a registered trademark of Sitecore Corporation A/S.
Sitecore Engage is a JavaScript library for sending behavioral data from a web application to Sitecore CDP.
Prerequisites
Before installing Sitecore Engage, you need:
- Node.js and npm.
- A web application (for example, React.js or Next.js).
Note A Sitecore JavaScript Rendering SDK (JSS) Next.js application with the
nextjs-personalize
add-on automatically installs Sitecore Engage. - Your Sitecore CDP client key, target URL, and point of sale.
Installation
npm install @sitecore/engage
Importing
import { init } from '@sitecore/engage';
Usage
This section describes using Sitecore Engage in a Next.js web application.
- In
index.js
, importuseEffect
from React andinit
from@sitecore/engage
.
import { useEffect } from 'react';
import { init } from '@sitecore/engage';
export default function Home() {
// ...
}
- In the
Home
function, create an asynchronous functionloadEngage
for loading the Engage API, then callloadEngage
in an Effect Hook.Tip We recommend that you use the Effect Hook because the
window
object must be present before you load the Engage API.
export default function Home() {
const loadEngage = async () => {
// ...
};
useEffect(() => {
loadEngage();
}, []);
return <></>;
}
-
In the
loadEngage
function:-
Load the Engage API by passing details about your Sitecore CDP instance to the
init()
function. Replace the placeholder values with your cookie domain, and your Sitecore CDP client key and target URL.Important
- The
init()
function is asynchronous, so you must await the return value. - In production, call the
init()
function in a module once, then share it across the application using the state management solution of your choice, for example, React Context or Redux.
- The
-
Start sending VIEW events to Sitecore CDP by passing event details to the
pageView()
function. Replace the placeholder values with event details specific to your organization. Replace the value forpointOfSale
with your Sitecore CDP point of sale.
-
const loadEngage = async () => {
// Load Engage API
const engage = await init({
clientKey: '{client_key_PLACEHOLDER}', // for example, "ZpHxO9WvLOfQRVPlvo0BqB8YjGYuFfNe"
targetURL: '{stream_api_target_endpoint_PLACEHOLDER}', // for example, "https://api-engage-eu.sitecorecloud.io"
cookieDomain: '{cookie_domain_PLACEHOLDER}', // for example, ".beta.myretailsite.com"
cookieExpiryDays: 365,
forceServerCookieMode: false,
});
// Send VIEW events
engage.pageView({
channel: '{channel_PLACEHOLDER}', // for example, "WEB"
currency: '{currency_PLACEHOLDER}', // for example, "EUR"
pointOfSale: '{point_of_sale_PLACEHOLDER}', // for example, "myretailsite/ireland"
});
};
- Reload your web application. Every time your webpage loads, a VIEW event is sent to Sitecore CDP.
Documentation and community resources
Contributions
We are very grateful to the community for contributing bug fixes and improvements. We welcome all efforts to evolve and improve Sitecore Engage; read below to learn how to participate in those efforts.
Code of Conduct
Sitecore has adopted a Code of Conduct that we expect project participants to adhere to. Please read the full text so that you can understand what actions will and will not be tolerated.
Contributing Guide
Read our contributing guide to learn about our development process, how to propose bug fixes and improvements, and how to build and test your changes to React.
License
Sitecore JavaScript Services is using the Apache 2.0 license.