@sitecore/engage

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, 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 asynchronous function loadEngage for loading the Engage API, then call loadEngage 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.

  • 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 for pointOfSale 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

• Official JSS documentation
• StackExchange
• Community Slack
• Sitecore Community Forum

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.

Support