Narwhal Parade Maestro

    @sitecore/engage
    TypeScript icon, indicating that this package has built-in type declarations

    0.4.0 • Public • Published

    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.

    1. 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() {
      // ...
    }
    1. 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 <></>;
    }
    1. In the loadEngage function:

      1. 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.
      2. 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"
      });
    };
    1. 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.

    Support

    Keywords

    none

    Install

    npm i @sitecore/engage

    DownloadsWeekly Downloads

    1,579

    Version

    0.4.0

    License

    Apache-2.0

    Unpacked Size

    108 kB

    Total Files

    66

    Last publish

    Collaborators

    • sc-evangeloslolos
    • appadmin-svc
    • sc-marklee
    • sc-jonasbangchristensen