@sitecore/engage

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, import useEffect from React and init from @sitecore/engage.

import { useEffect } from 'react';
import { init } from '@sitecore/engage';

export default function Home() {
  // ...
}

• In the Home function, create an empty, asynchronous function loadEngage for loading the Engage API, then call loadEngage 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.

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