JavaScript Personalize Edge SDK API Reference

The init() method initializes the SDK and must be called and awaited before use. It requests the Personalize Edge 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 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

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 in decreasing order.

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.

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.

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.

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.

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 getUserId() method retrieves the current user ID.

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 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.

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.

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.

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.

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.

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 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.

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 in decreasing order.

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 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.

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 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.

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 getUserId() method retrieves the current user ID.

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 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.

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.

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.

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.

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 SetUserIdOptions interface provides configuration options for the setUserId method.

The InitOptions interface specifies configuration options for initializing the SDK. These options allow for customization during the setup process

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.

The ManifestExperience type alias defines the structure of an experience within a personalization manifest.

The Manifest type alias defines the structure of the personalization manifest

The TriggerImpressionsOptions type alias defines the structure of the argument passed to the TriggerImpressionsOptions method.

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.