--- title: "JavaScript Personalize Edge SDK API Reference" description: "Reference guide for Contentstack's JavaScript Personalize Edge SDK: Explore features and functions for seamless content delivery in your projects" url: "https://www.contentstack.com/docs/developers/sdks/personalize-edge-sdk/javascript/reference" product: "Contentstack" doc_type: "guide" audience: - developers - admins version: "current" last_updated: "2025-02-19" --- # JavaScript Personalize Edge SDK API Reference ## JavaScript Personalize Edge SDK API Reference The JavaScript Edge SDK allows real-time content personalization across websites powered by Contentstack, mobile applications using React Native, and server-side environments such as Node.js. **Additional Resources:** To know more about the Personalize Edge SDK, refer to our [About Personalize Edge SDK](/docs/developers/sdks/personalize-edge-sdk/javascript/about-javascript-personalize-edge-sdk) and [Get Started with Personalize Edge SDK](/docs/developers/sdks/personalize-edge-sdk/javascript/get-started-with-javascript-personalize-edge-sdk) documentation. ## Personalize With [Personalize](/docs/personalize/about-personalize), you can create and manage audiences, define audience attributes, and develop tailored experiences for your users. You can then create personalized content for these experiences in the CMS using [Variants](/docs/personalize/about-variants). This SDK wraps around our [Edge API](/docs/developers/apis/personalize-edge-api) and enables you to retrieve a user’s active variants and deliver real-time personalized content based on user demographics, behavior, and preferences. **Note:** To configure a different Contentstack [region,](/docs/developers/contentstack-regions/about-regions) call the setEdgeApiUrl method before init(). By default, the SDK will attempt to initialize using the AWS NA region. ## init The init() method initializes the SDK and must be called and awaited before use. It requests the Personalize Edge [Manifest](/docs/developers/apis/personalize-edge-api#manifest) API and returns a promise that resolves to an SDK instance containing the current user's context, including active variants. This instance provides access to SDK features such as setting attributes, triggering events, and fetching variants. In browsers, if a manifest cookie exists (e.g., set by the addStateToResponse() method), the SDK bypasses the network request and uses the cookie. The personalize project UID. Options for initialization options. ## setEdgeApiUrl The setEdgeApiUrl() method configures the Edge API URL, especially when directing the SDK to a different Contentstack region. By default, the SDK will attempt to initialize using the AWS NA region. Invoke this method before initializing the SDK to ensure the configuration is applied. Refer to our documentation to find your region-specific [base URL](https://www.contentstack.com/docs/developers/apis/personalize-edge-api#base-url) The region-specific endpoint used to optimize SDK performance. ## getExperiences The getExperiences() method retrieves a list of experiences, each linked to its active variant's short UID. For inactive experiences, activeVariantShortUid will return null. The list is sorted by [experience priority](/docs/developers/apis/personalize-management-api#experiences-priority) in decreasing order. **Warning:** The use of getExperiences() as a global function in the global Personalize namespace is deprecated. To ensure compatibility and future support, initialize the SDK and use the getExperiences() method within the SDK instance. For more details, refer to [getExperiences()](/docs/developers/sdks/personalize-edge-sdk/javascript/reference#sdk-getexperiences) with an SDK Instance. ## triggerImpression The triggerImpression() method records an impression for a specified experience and sends it for the active variant as defined in the current user’s manifest. Use this method whenever an experience is displayed to the user. **Warning:** The use of triggerImpression() as a global function in the global Personalize namespace is deprecated. To ensure compatibility and future support, initialize the SDK and use the triggerImpression() method within the SDK instance. For more details, refer to [triggerImpression()](/docs/developers/sdks/personalize-edge-sdk/javascript/reference#sdk-triggerimpression) with an SDK Instance. The unique identifier of the experience for which the impression is to be triggered. ## triggerImpressions The triggerImpressions() method triggers multiple impressions for the given input. If provided with Experience Short UIDs, the impression is sent for the corresponding active variants in the manifest. If provided with Variant Aliases instead, it will use the Experience Short UID and Variant Short UID in the alias to trigger impressions, without referring to the manifest. **Warning:** The use of triggerImpressions() as a global function in the global Personalize namespace is deprecated. To ensure compatibility and future support, initialize the SDK and use the triggerImpressions() method within the SDK instance. For more details, refer to [triggerImpressions()](/docs/developers/sdks/personalize-edge-sdk/javascript/reference#sdk-triggerimpressions) with an SDK Instance. A Javascript object containing either experienceShortUids or aliases. Trigger impressions with either Experience Short UIDs or Variant Aliases. ## triggerEvent 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 Events module. This allows tracking conversions, analyzing user behavior, and measuring A/B test outcomes. **Warning:** The use of triggerEvent() as a global function in the global Personalize namespace is deprecated. To ensure compatibility and future support, initialize the SDK and use the triggerEvent() method within the SDK instance. For more details, refer to [triggerEvent()](/docs/developers/sdks/personalize-edge-sdk/javascript/reference#sdk-triggerevent) with an SDK Instance. Key for the event in Personalize ## set 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 Attributes module. **Warning:** The use of set() as a global function in the global Personalize namespace is deprecated. To ensure compatibility and future support, initialize the SDK and use the set() method within the SDK instance. For more details, refer to [set()](/docs/developers/sdks/personalize-edge-sdk/javascript/reference#sdk-set) with an SDK Instance. An object representing key-value pairs to define user traits, set on the client. ## setUserId The setUserId() method allows assigning a custom, externally managed user ID to the current user, overriding the automatically generated ID created during the SDK's first initialization. This is useful for scenarios like when an anonymous user logs in. If you want to retain previously tracked user attributes after assigning a new user ID, use the preserveUserAttributes option, which merges the current user's attributes into the new ID. In browser environments, this method sets a cookie (cs-personalize-user-id) to persist the user ID across sessions. **Note:** You can call this method either before or after initializing the SDK. **Warning:** The use of setUserId() as a global function in the global Personalize namespace is deprecated. To ensure compatibility and future support, initialize the SDK and use the setUserId() method within the SDK instance. For more details, refer to [setUserId()](/docs/developers/sdks/personalize-edge-sdk/javascript/reference#sdk-setuserid) with an SDK Instance. The new user ID for the current user. Pass options to preserve user attributes. ## getUserId The getUserId() method retrieves the current user ID. **Warning:** The use of getUserId() as a global function in the global Personalize namespace is deprecated. To ensure compatibility and future support, initialize the SDK and use the getUserId() method within the SDK instance. For more details, refer to [getUserId()](/docs/developers/sdks/personalize-edge-sdk/javascript/reference#sdk-getuserid) with an SDK Instance. ## getActiveVariant The getActiveVariant() method returns the short UID of the active variant for a specified experience, identified by its short UID. It returns null if the experience is not active or there are no variants active for the user. **Warning:** The use of getActiveVariant() as a global function in the global Personalize namespace is deprecated. To ensure compatibility and future support, initialize the SDK and use the getActiveVariant() method within the SDK instance. For more details, refer to [getActiveVariant()](/docs/developers/sdks/personalize-edge-sdk/javascript/reference#sdk-getactivevariant) with an SDK Instance. The unique identifier for an experience, available in the Personalize Experiences page or through a variant alias. ## getInitializationStatus The getInitializationStatus() method provides the current status of SDK initialization. The status transitions to initializing when the SDK starts initializing, updates to success upon completion, and changes to error if an issue occurs. **Note:** Use this method to verify that the SDK has been fully initialized before calling other SDK methods. ## addStateToResponse The addStateToResponse() helper method appends user state information, including the user ID and current manifest, as set-cookie headers to the provided response object. This method is typically used in edge functions to efficiently manage user state tracking. By using this approach, the Personalize SDK can initialize in the browser without needing a network call to retrieve the manifest. **Warning:** The use of addStateToResponse() as a global function in the global Personalize namespace is deprecated. To ensure compatibility and future support, initialize the SDK and use the addStateToResponse() method within the SDK instance. For more details, refer to [addStateToResponse()](/docs/developers/sdks/personalize-edge-sdk/javascript/reference#sdk-addstatetoresponse) with an SDK Instance. A standard web response object used to append set-cookie headers for managing user state. ## getVariants The getVariants() method retrieves the active variants as key-value pairs, where the keys are experience short UIDs and the values are variant short UIDs. For inactive experiences, the values will be null. **Warning:** The use of getVariants() as a global function in the global Personalize namespace is deprecated. To ensure compatibility and future support, initialize the SDK and use the getVariants() method within the SDK instance. For more details, refer to [getVariants()](/docs/developers/sdks/personalize-edge-sdk/javascript/reference#sdk-getvariants) with an SDK Instance. ## getVariantAliases The getVariantAliases() method retrieves a list of active experiences represented as variant aliases. These aliases are used by Personalize to identify CMS variants and can be passed to the CMS Delivery API to fetch personalized content entries. The list is ordered by priority, with higher-priority variants appearing earlier. **Warning:** The use of getVariantAliases() as a global function in the global Personalize namespace is deprecated. To ensure compatibility and future support, initialize the SDK and use the getVariantAliases() method within the SDK instance. For more details, refer to [getVariantAliases()](/docs/developers/sdks/personalize-edge-sdk/javascript/reference#sdk-getvariantaliases) with an SDK Instance. ## getVariantParam The getVariantParam() method returns an opaque variant parameter, formatted as a comma-separated list of active experience and variant short UIDs. This parameter is designed to be easily included in a URL as a query parameter, enabling the transfer of the active variants for the current user. This method is commonly used in edge functions to streamline the handling of variant information. **Warning:** The use of getVariantParam() as a global function in the global Personalize namespace is deprecated. To ensure compatibility and future support, initialize the SDK and use the getVariantParam() method within the SDK instance. For more details, refer to [getVariantParam()](/docs/developers/sdks/personalize-edge-sdk/javascript/reference#sdk-getvariantparam) with an SDK Instance. ## variantParamToVariantAliases The variantParamToVariantAliases() method decodes a variant parameter into a list of variant aliases. This parameter, often used as a query parameter in URLs, represents the variants activated for the current user. This method is typically used in server-side code to transform the variant parameter into a list of aliases, which can then be passed to the CMS Delivery API for fetching personalized content. The variant param generated by Personalize.getVariantParam() ## reset The reset() method reverts the SDK to its original state by performing the following actions: * Deletes the manifest. * Clears the user ID. * Removes any associated cookies in browser environments. This method ensures a clean slate for the SDK's operation. **Warning:** The use of reset() method in the global Personalize namespace is deprecated. As part of the transition to use the SDK instance, Personalize.reset() is no longer required and will be removed in a future release. ## SDK The SDK class contains the primary functionality of the SDK. An instance of this SDK class is created and returned when you call Personalize.init ## getExperiences The getExperiences() method retrieves a list of experiences, each linked to its active variant's short UID. For inactive experiences, activeVariantShortUid will return null. The list is sorted by [experience priority](/docs/developers/apis/personalize-management-api#experiences-priority) in decreasing order. ## triggerImpression The triggerImpression() method records an impression for a specified experience and associates it with the active variant defined in the current user’s manifest. Use this method whenever an experience is displayed to the user to ensure accurate tracking. The unique identifier of the experience for which the impression is to be recorded. ## triggerImpressions The triggerImpressions() method triggers multiple impressions for the given input. If provided with Experience Short UIDs, the impression is sent for the corresponding active variants in the manifest. If provided with Variant Aliases instead, it will use the Experience Short UID and Variant Short UID in the alias to trigger impressions, without referring to the manifest. A Javascript object containing either experienceShortUids or aliases. Trigger impressions with either Experience Short UIDs or Variant Aliases. ## triggerEvent The triggerEvent() method records important user actions, such as clicking a CTA or scrolling to the end of a page. It requires an eventKey a unique identifier defined in the Personalize Events module, to track conversions, analyze user behavior, and measure A/B test outcomes. The unique key for the event in Personalize. ## set The set() method allows you to define user attributes as key-value pairs representing user traits. To use these attributes, ensure that matching keys are created in the Personalize Attributes module. Setting user attributes is an async operation, as they are sent to Personalize’s edge network using the Edge API. An object containing key-value pairs that define user traits on the client. ## setUserId The setUserId() method allows assigning a custom, externally managed user ID to the current user, overriding the automatically generated ID created during the SDK's first initialization. This is useful for scenarios like when an anonymous user logs in. If you want to retain previously tracked user attributes after assigning a new user ID, use the preserveUserAttributes option, which merges the current user's attributes into the new ID. In browser environments, this method sets a cookie (cs-personalize-user-id) to persist the user ID across sessions. **Note:** You can call this method either before or after initializing the SDK. The new user ID for the current user. To retain previously tracked user data. ## getUserId The getUserId() method retrieves the current user ID. ## getActiveVariant The getActiveVariant() method returns the short UID of the active variant for a specified experience, identified by its short UID. It returns null if the experience is not active or there are no variants active for the user. The unique identifier for an experience, available in the Personalize Experiences page or through a variant alias. ## addStateToResponse The addStateToResponse() helper method appends user state information, including the user ID and current manifest, as set-cookie headers to the provided response object. This method is typically used in Edge Functions to efficiently manage user state tracking. By using this approach, the Personalize SDK can initialize in the browser without needing a network call to retrieve the manifest. A standard web response object used to append set-cookie headers for managing user state. ## getVariants The getVariants() method retrieves the active variants as key-value pairs, where the keys are experience short UIDs and the values are variant short UIDs. For inactive experiences, the values will be null. ## getVariantAliases The getVariantAliases() method retrieves a list of active experiences represented as variant aliases. These aliases are used by Personalize to identify CMS variants and can be passed to the CMS Delivery API to fetch personalized content entries. The list is ordered by priority, with higher-priority variants appearing earlier. ## getVariantParam The getVariantParam() method returns an opaque variant parameter, formatted as a comma-separated list of active experience and variant short UIDs. This parameter is designed to be easily included in a URL as a query parameter, enabling the transfer of the active variants for the current user. This method is commonly used in edge functions to streamline the handling of variant information. ## variantParamToVariantAliases The variantParamToVariantAliases() method decodes a variant parameter into a list of variant aliases. This parameter, often used as a query parameter in URLs, represents the variants activated for the current user. This method is typically used in server-side code to transform the variant parameter into a list of aliases, which can then be passed to the CMS Delivery API for fetching personalized content. The variant param generated by Personalize.getVariantParam() ## Types and Interfaces The Types and Interfaces used and exported by the Personalize Edge SDK. ## SetUserIdOptions The SetUserIdOptions interface provides configuration options for the setUserId method. Set to true to merge user attributes from the current user. ## InitOptions The InitOptions interface specifies configuration options for initializing the SDK. These options allow for customization during the setup process A web-standard Request object used to track users and extract attributes like query parameters, referrer, and geolocation in edge functions. The user ID to be explicitly assigned. Specifies a custom name for the variant query parameter Specifies the custom attributes object to treat as live attributes. These attributes must be pre-configured in the Personalize project. ## ClientAttributes The ClientAttributes type alias represents a collection of key-value pairs, where each key is an attribute key that you have defined in the Attributes module, and the corresponding value can be of the type expected by the audience rules. ## ManifestExperience The ManifestExperience type alias defines the structure of an experience within a personalization manifest. The unique identifier for the experience. The unique identifier for the active variant associated with the experience; it can be null if no variant is active. ## Manifest The Manifest type alias defines the structure of the personalization manifest A record mapping experience short UIDs to their corresponding active variant short UIDs An array of ManifestExperience objects, each representing an experience and its associated active variant. ## TriggerImpressionsOptions The TriggerImpressionsOptions type alias defines the structure of the argument passed to the TriggerImpressionsOptions method. A list of Experience Short UIDs. The corresponding active variants are picked from the Manifest. A list of Variant Aliases. An alias consists of an Experience Short UID and a corresponding Variant Short UID. ## InitializationStatus The InitializationStatus type alias defines in the Contentstack Personalize SDK represents the current state of the SDK's initialization process. It can have one of the following string values: * initializing: Indicates that the SDK is in the process of initializing. * success: Signifies that the SDK has successfully initialized. * error: Denotes that an error occurred during the initialization.