A Strong Performer in The Forrester Wave™: Digital Experience Platforms, Q4 2025
Contentstack
Changelog

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

More articles in "Edge SDK"