Get Started with JavaScript Personalize Edge SDK

The SDK is a wrapper over the Personalize Edge API, which is the decision engine that determines the variants to be shown to a user as well as the endpoint to track user impressions and events.
This step-by-step guide will help you get started with the JavaScript Personalize Edge SDK and build personalized applications powered by Contentstack.

Prerequisites

• Website content sourced from a Contentstack stack
• Personalize project created and connected to a stack
• Personalize Project UID

Installing and Setup

If you are working with a Node.js-based project, use the following command to install the SDK:

$ npm i @contentstack/personalize-edge-sdk

Note: For NPM-based browser projects, use the same installation command as above.

Initialize the SDK

Initialization ensures the SDK can retrieve user-specific experiences, track impressions, and log events. The initialization process varies depending on the context in which the SDK is being used, such as edge middleware, backend, or frontend.

Initialization involves an API call to the Edge API to fetch the manifest for the current user. This manifest is maintained throughout the SDK’s lifespan. Methods such as getExperiences and getVariantAliases rely on this manifest to provide their outputs.

To start using the SDK, import and configure it with your Project UID:

import Personalize from '@contentstack/personalize-edge-sdk';
let projectUid = 'your-project-uid';
// Using async-await:
await Personalize.init(projectUid);

Initializing the SDK at the backend

In backend environments like edge middleware or an origin server, the SDK can retrieve user variants based on incoming requests. Since the context resides in the request object, you can pass it directly during initialization. The SDK uses the request to extract relevant data such as URL, IP address (for location-based personalization), referrer, device, and operating system.

await Personalize.init(projectUid, {
	userId: 'your-users-id', // optional
	request, // the JavaScript request object for the request incoming from a user's browser
});

Initializing the SDK in the browser

In browser environments, you can initialize the SDK to track impressions and events. In client-side rendered applications, it also retrieves active variants for the current user, enabling real-time personalized content delivery.
As the browser lacks request context, the initialization is straightforward:

await Personalize.init(projectUid, {
	userId: 'your-users-id', // optional
});

Retrieve Experiences

Get the list of all the experiences in your project and their respective active variants. The experiences are sorted in decreasing order of priority, as defined in the Management Console.

const experiences = Personalize.getExperiences();
// [{shortUid: 'a', activeVariantShortUid: '0'}, {shortUid: 'b', activeVariantShortUid: '1'}]

Retrieve Variant Aliases for Content Delivery

Get the list of Variant Aliases, which can be passed to the CMS Delivery API to fetch personalized entry variants.

const variantAliases = Personalize.getVariantAliases();
// ['cs_personalize_a_0', 'cs_personalize_b_1']

Trigger an Event

The triggerEvent() method records significant user actions, such as clicking a CTA or scrolling to the end of a page, by passing an eventKey—a unique identifier defined in the Personalize Management Console. This allows tracking conversions, analyzing user behavior, and measuring A/B test outcomes. Ensure the method is called post initializing the SDK.

await Personalize.triggerEvent('clickCTA');

Set Custom User Attributes

The set method allows you to define user attributes as key-value pairs representing user traits. To use these attributes, create them with matching keys in the Personalize Management Console. Ensure the SDK is initialized before calling this method.

Note: Since the user attributes data is stored at our edge network around the world, please note that it may take up to one second for newly set attributes to be considered by our decision engine in determining the user's variants.

await Personalize.set({ age: 20 });

Resources

• Setup Next.js Website with Personalize - Launch
• Setup Next.js Website with Personalize - Vercel

Next Steps

Personalize Edge SDK API Reference