# 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](https://doc.sitecore.com/personalize/en/developers/api/index-en.html?contextId=UEpjHJ) 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`](https://doc.sitecore.com/xmc/en/developers/xm-cloud/the-next-js-personalize-add-on.html) add-on automatically installs Sitecore Engage.
- [Details](https://doc.sitecore.com/personalize/en/developers/api/index-en.html?contextId=LUouSS) about your Sitecore CDP or Sitecore Personalize instance: your client key, target URL, and point of sale.

## Installation

```bash
npm install @sitecore/engage
```

## Importing

```js
import { init } from '@sitecore/engage';
```

## Usage

This section describes how to start using Sitecore Engage in a Next.js (version 12) app.

1. In `index.js`, import `useEffect` from React and `init` from `@sitecore/engage`.

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

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

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

```js
export default function Home() {
  const loadEngage = async () => {
    // ...
  };

  useEffect(() => {
    loadEngage();
  }, []);

  return <></>;
}
```

3. In the `loadEngage` function:

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

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

```js
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](https://doc.sitecore.com/personalize/en/developers/api/index-en.html?contextId=UEpjHJ)
- [Official Sitecore Engage reference documentation](https://doc.sitecore.com/personalize/en/developers/api/index-en.html?contextId=9SQnc0)
- [Official JSS documentation](https://doc.sitecore.com/xp/en/developers/hd/201/sitecore-headless-development/sitecore-javascript-rendering-sdks--jss-.html)
- [StackExchange](https://sitecore.stackexchange.com/)
- [Community Slack](https://sitecorechat.slack.com/messages/jss)
- [Sitecore Community Forum](https://community.sitecore.net/developers/f/40)

### License

Sitecore Engage uses the [Apache 2.0 license](https://www.apache.org/licenses/LICENSE-2.0).