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({
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!