JavaScript Personalize Edge SDK v1.0.9+ Migration Guide

Note: This guide applies to v1.x.x of the Personalize Edge SDK using global functions in the Personalize namespace. For implementation details refer to the Get Started with JavaScript Personalize Edge SDK and JavaScript Personalize Edge SDK API Reference documentation.

JavaScript Personalize Edge SDK version 1.0.9 introduces a new instance-based approach, replacing the global Personalize namespace. You should now create an SDK class instance and call its methods.

Warning: The global functions are now deprecated and will be removed in the next major release, for the exact list of deprecated methods, see Deprecated Global Functions section.

Example

With Global Personalize namespace:

import Personalize from '@contentstack/personalize-edge-sdk';

await Personalize.init('<your_project_uid>');

// start using the SDK
const variants = Personalize.getVariants();

With instance-based approach (Version 1.0.9 and later):

import Personalize from '@contentstack/personalize-edge-sdk';

const personalizeSdk = await Personalize.init('<your_project_uid>');

// start using the SDK
const variants = personalizeSdk.getVariants();

Why Upgrade?

While the global Personalize namespace was generally effective, with one significant exception. When using the SDK in edge middleware or at the origin, storing data globally under high traffic conditions can cause data leakage across requests, which may result in active variants from one request to be incorrectly served to another.

The instance-based approach in v1.0.9 eliminates this issue, ensuring each request is handled independently and prevents unintended data sharing.

Migration Steps

To transition from the global Personalize namespace to the new instance-based approach, follow these steps:

1. Upgrade the SDK to the latest version

   To ensure your project is using the latest version of the Personalize Edge SDK, run the following command:

   npm i @contentstack/personalize-edge-sdk@latest

2. Update your SDK initialization code to store the SDK instance

   Modify your code to store the SDK instance returned by the init function:

   import Personalize from '@contentstack/personalize-edge-sdk';
   
   // store the promised value by the init function in a variable
   const personalizeSdk = await Personalize.init('<your_project_uid>');

3. Replace the usage of global functions with SDK instance methods

   Update all function calls to use the SDK instance instead of the global Personalize namespace.

   // to get the current user's variants
   const activeVariants = personalizeSdk.getVariants();
   
   // to trigger an impression
   await personalizeSdk.triggerImpression('<experience_short_uid>');
   
   // to get variant aliases
   const aliases = personalizeSdk.getVariantAliases();
   
   // similarly for the other methods listed below

4. Remove the Personalize.reset() method

   The reset function is deprecated and will be removed in the next major version. Since the SDK now uses instances, resetting the SDK is no longer necessary, instead, create a new instance and discard the older one.

5. Test your code to ensure it still works as expected

   Now that the required changes have been made, it is time to test that all functionality remains as expected. Once testing is complete, you are ready to go live!

Deprecations

The Personalize Edge SDK remains backwards compatible with the older functions till v1.x.x, but the support will be removed in v2.x.x.

Deprecated Global Functions

The following functions should be called on the SDK instance instead of the Personalize namespace.

• getExperiences
• triggerImpression
• triggerImpressions
• triggerEvent
• set
• setUserId
• getUserId
• getActiveVariant
• addStateToResponse
• getVariants
• getVariantAliases
• getVariantParam

Planned Removals in the Next Major Version

• reset

More Resources

• JavaScript Personalize Edge SDK API Reference
• Get Started with JavaScript Personalize Edge SDK
• Setup Next.js Website with Personalize - Launch