A Typescript Compatible Sitecore CDP and Personalize NPM Package

Introduction

If your project is built on Typescript and you’ve tried to integrate Boxever (Sitecore CDP and Personalize) JavaScript Library into your solution, you probably noticed that it’s not as easy as importing Sitecore’s library and then using the window global object. So, what can we do? Sitecore-cdp-personalize npm package to the rescue! I built this package specifically to work around this Typescript problem, but it will also work with any node-based front-end development environment. My biggest goal with this package was to keep methods and usage as close to Sitecore’s OOTB library. There are some tweaks I’ve made to make it easier to use, like automatically injecting browserId and clientKey for certain methods, but if you’re familiar with Sitecore’s library OOTB methods, this library will be an easy transition.

Usage

To begin, you'll need to add Sitecore-cdp-personalize to your project

npm install sitecore-cdp-personalize

Then, anywhere in your application, initialize the library. If you’re not sure what values to use to initialize the library, check out how to setup CDP and Personalize, which covers how to gather the required details.

import { cdpPersonalize } from 'sitecore-cdp-personalize';

//Configure CDP and Personalize, and injects Boxever (CDP and Personalize) JavaScript Library into page
cdpPersonalize.initialize(
  '[CLIENT_KEY]',
  '[API_TARGET]',
  '[COOKIE_DOMAIN]',
  '[POINT_OF_SALE]',
  '[WEB_FLOW_TARGET]',
  '[LIBRARY_VERSION]', // optional, defaults to 1.4.9
  '[CURRENCY]', // optional, defaults to USD
  '[CHANNEL]', // optional, defaults to WEB
  '[LANGAUGE]' // optional, defaults to EN
);

That’s it! Boxever (Sitecore CDP and Personalize) JavaScript Library is ready to be used on your website.

Supported Features

At this point, the Sitecore CDP and Personalize JavaScript should be running on your website, but you’ll likely want to do more than just install it on the website. The package will support all the methods that the Sitecore OOTB library supports. Here is a list of the methods you'll most likely use:

identifyByEmail

Used to identify a user using their email as the ID.

cdpPersonalize.identifyByEmail(
  'example@email.com', // id: required
  {
    // optionally, send any additional properies you need
    customProperties: 'example value',
  }
);

eventCreate

Used to submit an event to CDP and Personalize. Internally, the library automatically adds the following properties for you:

• Page
• Currency
• POS
• browser_id
• channel
• language
• UTM parameters from URL

cdpPersonalize
  .eventCreate({
    type: 'EVENT_NAME', // "type" is required by CDP and Personalize
    extraData: 'example of extra information', // optionally, you can add any other properies you need
  })
  .then(response => console.log(response.status));

callFlows

Used to execute a flow. Internally, the library automatically adds the following properties for you:

• Page
• Currency
• POS
• browser_id
• channel
• language
• clientKey

type customReponse = {
  userInterest: String;
  otherProperies: Boolean;
};

cdpPersonalize
  .callFlows<customReponse>({
    friendlyId: 'CDP_PERSONALIZE_FLOW_FRIENDLY_ID', // required
    otherPropsYouNeed: 'example value', // optioanlly, send any other properties you need
  })
  .then(response => {
    console.log(response.userInterest);
  });

trackPage

Used to track the user navigating pages. If your application is a SPA, make sure to call this method every time the user navigates within your application.

cdpPersonalize.trackPage().then(response => console.log(response.status));

getGuestRef

Used to get the user's current guest reference.

cdpPersonalize.getGuestRef().then(ref => console.log(ref));

browserShow

Used to get the user's information.

cdpPersonalize.browserShow().then(data => console.log(data.customer));

A full list of methods can be found at: https://www.npmjs.com/package/sitecore-cdp-personalize

Conclusion

Integrating Boxever (Sitecore CDP and Personalize) JavaScript Library into a typescript project can be a bit more complex than a typical installation, but with the help of the Sitecore-cdp-personalize npm package, it’s just as easy, if not easier!