@sitecore/engage
v1.4.3
Published
© Sitecore Corporation A/S. All rights reserved. Sitecore© is a registered trademark of Sitecore Corporation A/S.
Downloads
28,085
Keywords
Readme
Sitecore Engage
© Sitecore Corporation A/S. All rights reserved. Sitecore© is a registered trademark of Sitecore Corporation A/S.
Sitecore Engage lets you send behavioral and transactional data from your web application to Sitecore CDP or Sitecore Personalize.
Prerequisites
Before installing Sitecore Engage, you need:
- Access to Sitecore CDP or Sitecore Personalize, or both.
- Node.js version 18 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. - Details about your Sitecore CDP or Sitecore Personalize instance: your client key, target URL, and point of sale.
Installation
npm install @sitecore/engage
Importing
import { init } from '@sitecore/engage';
Usage
This section describes how to start using Sitecore Engage in a Next.js (version 12) app.
- 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 empty, asynchronous functionloadEngage
for loading the Engage API, then callloadEngage
in an Effect Hook.Tip You should 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 or Sitecore Personalize instance to the
init()
function. Replace the placeholder values with your client key, target URL, point of sale, and cookie domain.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 or Sitecore Personalize by passing event details to the
pageView()
function. Replace the placeholder values with event details specific to your organization.
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"
pointOfSale: '<point_of_sale_PLACEHOLDER>', // for example, "myretailsite/ireland"
cookieDomain: '<cookie_domain_PLACEHOLDER>', // for example, ".beta.myretailsite.com" or "localhost"
cookieExpiryDays: 365,
forceServerCookieMode: false,
includeUTMParameters: true,
webPersonalization: true,
});
// Send VIEW events
const eventData = {
channel: '<channel_PLACEHOLDER>', // for example, "WEB"
currency: '<currency_PLACEHOLDER>', // for example, "EUR"
};
const optionalExtensionData = {
customKey: 'customValue',
};
engage.pageView(eventData, optionalExtensionData);
};
Every time your webpage loads, a VIEW event is sent. You can verify this on the Network tab of your web browser's developer tools.
Documentation and community resources
- Official Sitecore Engage integration documentation
- Official Sitecore Engage reference documentation
- Official JSS documentation
- StackExchange
- Community Slack
- Sitecore Community Forum
License
Sitecore Engage uses the Apache 2.0 license.