sitecore-cdp-personalize
v1.0.4
Published
The sitecore-cdp-personalize library is used to quickly integrate with Boxever (Sitecore CDP and Personalize) JavaScript Library.
Downloads
4
Readme
Sitecore CDP and Personalize
The sitecore-cdp-personalize library is used to quickly integrate with Boxever (Sitecore CDP and Personalize) JavaScript Library.
Features
- Typescript Support
- Easy to use wrapper over Boxever (Sitecore CDP and Personalize) JavaScript Library
- Retry mechanism to ensure Boxever is properly loaded
- Promise-based
Usage
Installaion
npm install sitecore-cdp-personalize
Core Setup
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
);
Common methods
//Identify Users
cdpPersonalize.identifyByEmail('[email protected]');
cdpPersonalize.identifyByProvider('customer_id', '1234567');
//Track Page Views
cdpPersonalize.trackPage();
//Create Events
cdpPersonalize.eventCreate({
type: 'CUSTOM_EVENT', // "type" is required by CDP and Personalize
extraData: 'example of extra information', // optionally, you can add any other properies you need
});
Server Side (APIs)
Server side calls have been split into a different package, sitecore-cdp-personalize-api.
Methods
- initialize
- trackPage
- identifyByEmail
- identifyByProvider
- eventCreate
- callFlows
- browserShow
- getBrowserId
- getGuestRef
- getBucketNumber
- getClientKey
- getCookie
- reset
- triggerExperiences
initialize
Used to configure what values CDP and Personalize is configured with. It also injects the Boxever (Sitecore CDP and Personalize) JavaScript Library into the head of the page. All other methods require that the initialize method is called at least once in the application.
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
);
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. You must call initialize before using trackPage().
cdpPersonalize.trackPage().then(response => console.log(response.status));
returns: a promise containing the HTTP status of the CDP and Perosnalize response.
identifyByEmail
Used to identify a user using their email as the ID. You must call initialize before using identifyByEmail().
cdpPersonalize.identifyByEmail(
'[email protected]', // id: required
{
// optionally, send any additional properies you need
customProperties: 'example value',
}
);
returns: a promise containing the HTTP status of the CDP and Perosnalize response.
identifyByProvider
Used to identify a user using a custom identity provider and ID. You must call initialize before using identifyByProvider().
cdpPersonalize.identifyByProvider(
'employee_id', // provider: required
'716251', // id: required
{
// optionally, send any additional properies you need
customProperties: 'example value',
}
);
returns: a promise containing the HTTP status of the CDP and Perosnalize response.
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
You must call initialize before using eventCreate().
cdpPersonalize
.eventCreate({
type: 'CUSTOM_EVENT', // "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));
returns: a promise containing the HTTP status of the CDP and Perosnalize response.
callFlows
Used to execute a flow. Internally, the library automatically adds the following properties for you:
- Page
- Currency
- POS
- browser_id
- channel
- language
- clientKey
You must call initialize before using eventCreate().
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);
});
returns: a promise containg the response from the flow, mapped to the type provided.
browserShow
Used to get the user's information. You must call initialize before using browserShow().
cdpPersonalize.browserShow().then(data => console.log(data.customer));
returns: a promise containing the customer object.
getBrowserId
Used to get the user's current browserId. You must call initialize before using getBrowserId().
cdpPersonalize.getBrowserId().then(browserId => console.log(browserId));
returns: a promise containing the user's current browserId.
getGuestRef
Used to get the user's current guest reference. You must call initialize before using getGuestRef().
cdpPersonalize.getGuestRef().then(ref => console.log(ref));
returns: a promise containing the user's guest reference.
getBucketNumber
Used to update the bucket number cookie to match the latest bucket number in Sitecore CDP. You should call this after an IDENTITY event.
cdpPersonalize.getBucketNumber().then(bucketNumber => {
console.log(bucketNumber);
});
returns: a promise containing the user's updated bucket number.
getClientKey
Used to retrieve the client key. You must call initialize before using getClientKey().
cdpPersonalize.getClientKey().then(clientKey => {
console.log(clientKey);
});
returns: a promise containing the client key.
getCookie
Used to retrieve cookie value. This only works for cookies set by Boxever (Sitecore CDP and Personalize) and cookies set by setCookie() (setCookie coming soon). You must call initialize before using getCookie().
cdpPersonalize.getCookie('bx_bucket_number').then(cookieValue => {
console.log(cookieValue);
});
returns: a promise containing the cookie's value.
reset
Used to reinitialize the Boxever (Sitecore CDP and Personalize) JavaScript Library. It will clear the event queue, deletes the browser ID and guest reference, and reloads the javascript library.
cdpPersonalize.reset().then(() => {
console.log('Values reset');
});
triggerExperiences
Used to rerun all the web experiences and experiments.
cdpPersonalize.triggerExperiences().then(() => {
console.log('Experiences triggered');
});