SDK

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.

Example:

personalizeSdk.getExperiences(); // [{shortUid: 'a', activeVariantShortUid: '0'}]

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.

Example:

const experienceShortUid = 'a';
await personalizeSdk.triggerImpression(experienceShortUid);

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.

Example:

const experienceShortUids = ['a', 'b'];
await personalizeSdk.triggerImpressions({ experienceShortUids });
await personalizeSdk.triggerImpressions({ aliases: ['cs_personalize_a_0', 'cs_personalize_b_1'] });

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.

Example:

await personalizeSdk.triggerEvent('clickCTA');

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.

Example:

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

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.

NoteYou can call this method either before or after initializing the SDK.

Example:

await personalizeSdk.setUserId(newUserId, { preserveUserAttributes: true });

The getUserId() method retrieves the current user ID.

Example:

const userId = personalizeSdk.getUserId();

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.

Example:

const activeVariant = personalizeSdk.getActiveVariant(experienceShortUid);

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.

Example:

await personalizeSdk.addStateToResponse(response);

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.

Example:

personalizeSdk.getVariants(); // {a: 0, b: 1}

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.

Example:

personalizeSdk.getVariantAliases(); // ['cs_personalize_a_0', 'cs_personalize_b_1']

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.

Example:

personalizeSdk.getVariantParam(); // 'a_0,b_1'

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.

Example:

const variantParam = personalizeSdk.getVariantParam(); // 'a_0,b_1'
personalizeSdk.variantParamToVariantAliases(variantParam); // ['cs_personalize_a_0', 'cs_personalize_b_1']