Dynamically Track Variant Impressions Based On Entry Variant Shown

Use dynamic impression tracking with the Personalize Edge SDK’s triggerImpression() method to support entries with multiple experiences and variants. You can extract the applied variants from the Content Delivery API (CDA) response and programmatically trigger impressions based on the resolved variant aliases.

We recommend this approach to minimize developer involvement when rolling out new and updated experiences. The CDA response includes a publish_details.variants object, which shows the resolved variant(s) for a specific entry based on active experiences and audience conditions determined by Personalize.

This guide explains how to:

• Retrieve the active variant data for a user from the Personalize Edge API – Manifest endpoint
• Identify the applied variants dynamically from the entry response
• Use triggerImpressions() to register impressions for each visible variant

Why This Is Important

When using Personalize, experiences and variants are resolved dynamically at runtime based on the user’s audience membership. Because the content served can be a dynamic mix of variants, it is essential to extract the applied variants from the CDA response. This ensures your impression tracking reflects exactly what was shown to the user, enabling accurate measurement and analytics.

Prerequisites

• Contentstack Personalize SDK initialized on the page
• Entry retrieved via Contentstack CDA (REST, GraphQL, or SDK)
• Experience(s) configured in Personalize
• At least one variant created and applied on the entry
• JavaScript runtime (Node/browser) (optional)

Steps for Execution

1. Retrieve the active variants for a user using Personalize Edge
2. Query the Entry via CDA
3. Extract Variant Aliases from the Response
4. Trigger Impressions

1. Retrieve the Active Variants for a User Using Personalize Edge

   The GET Manifest endpoint, also known as the Manifest API, returns the active variants for a user. When a user visits your site, Personalize evaluates all Active Experiences configured for that page and determines which variant to show for each experience.

   This variant alias can then be used to request the personalized entry content from the Contentstack Content Delivery API (CDA).

   Note: The manifest only indicates which variant should be displayed, not whether the variant content actually exists or was rendered. Only trigger impressions after confirming that the corresponding variant content was retrieved and shown on the page.

   Example: JavaScript Edge SDK

   import Personalize from '@contentstack/personalize-edge-sdk';
   const personalizeSDK = await Personalize.init(projectUid);
   const variantAliases = personalizeSDK.getVariantAliases();
   console.log(variantAliases); // example: ['cs_personalize_0_0', 'cs_personalize_1_1']

   Example: REST API (GET /manifest)

   curl -X GET 'https://personalize-edge.contentstack.com/manifest' \
     -H 'X-Project-Uid: <your_personalize_project_uid>' \
     -H 'Cookie: cs_personalize_user_uid=<anonymous_user_id>' \
     -H 'X-Page-Url: https://www.mysite.com/homepage'

   Sample Response:

   {
     "experiences": [
       {
         "shortUid": "0",
         "activeVariantShortUid": "0"
       },
       {
         "shortUid": "1",
         "activeVariantShortUid": "1"
       }
     ]
   }

   Note: Replace the request URL domain, x-project-uid header, and cs_personalize_user_uid cookie with actual values.

2. Query the Entry via CDA

   Use the active variants to fetch personalized entry data via the Contentstack CDA (REST, GraphQL, or SDK). Make sure to include the publish_details field to access applied variant metadata.

   REST API: Entry variant API
   SDK: Get Variants

   Each key in the variants object is a Variant UID. Each value includes an alias in the format cs_personalize_<experience_uid>_<variant_uid>.

   {
     "entry": {
       "title": "Dynamic Banner",
       "publish_details": {
         "variants": {
           "<first_variant_uid>": {
             "alias": "cs_personalize_0_0",
             "environment": "<your_environment>"
           },
           "<second_variant_uid>": {
             "alias": "cs_personalize_1_1",
             "environment": "<your_environment>"
           }
         }
       }
     }
   }

   Note: Each value includes metadata, including the alias, which is needed to register impressions.

3. Extract Variant Aliases from the Response

   You can extract variant aliases using the CDA response. These aliases are required to register impressions using the triggerImpressions() method or the Edge API.

   const variants = entry?.publish_details?.variants || {};
   const variantAliases = Object.values(variants).map((v) => v.alias);

4. Trigger Impressions

   Once you have extracted the active variant aliases, register impression events for each one. This step is critical for tracking which variants were shown to the user and measuring the performance of your personalization efforts.

   Using the SDK

   // after initializing the SDK
   personalizeSDK.triggerImpressions({
     aliases: variantAliases
   });

   Note: Ensure the variant content is rendered before calling triggerImpressions() to avoid false impressions.

   Using the API Directly

   curl -X POST 'https://personalize-edge.contentstack.com/events' \
     --header 'x-cs-personalize-user-uid: <user_id>' \
     --header 'x-project-uid: <project_uid>' \
     --header 'Content-Type: application/json' \
     --header 'Accept: application/json' \
     --data '[
       {
         "type": "IMPRESSION",
         "experienceShortUid": "0",
         "variantShortUid": "0"
       },
       {
         "type": "IMPRESSION",
         "experienceShortUid": "1",
         "variantShortUid": "1"
       }
     ]'

   Replace all placeholder values with the actual values from your project setup.

Best Practices

• Always validate that publish_details.variants exists before proceeding.
• Avoid duplicate impression events for the same variant on the same page load.
• Use the Manifest API for determining the current audience-selected variants.
• Use the CDA response only if content rendering depends on the returned entry structure.