Client-side template implementation notes and tips

Important implementation notes

• Support for multiple variations:
  Only API Custom Code campaigns currently support multiple variations. This means that for API Recommendation campaigns, response choice objects return only 1 variation.
• Controlling returned values in API Recommendation campaign responses:
  The recProductData feature under the options object in the Choose call request enables you to control the values returned in the response: Either SKUs only, or a list of values in the fieldFilter list. The parameter overrides any definition in the client-side template, so make sure to align how you use this feature with the client-side templates.

Implementation tips

Easier engagement reporting

We recommended that you add the following attributes to any element rendered:

• API Custom Code campaigns: decisionId and variationId are necessary to report impressions and clicks.
• API Recommendations campaigns: Use decisionId and slotId to report impressions and slot-clicks.

Caching templates

We recommend working with some type of caching mechanism for the template files to improve performance. As template changes seldom correspond to template fetching frequency in runtime, and the fact that with each change a new token is created, there's no need to apply any version control logic on your side. Capping the lifecycle of the template (meaning deleting from the cache) after a 48 hours is sufficient to maintain a minimal cache as any edit to the template generates a brand new token.

Syncing your cache using a selector group

To sync your cache you'll need to obtain all the template tokens, which will enable you to retrieve the template files from the CDN (regardless of user activity). For each template, create a new campaign in Experience OS whose only purpose is to return the template object (for example, a campaign called "Get Banner template"). The campaign should not have any targeting conditions, and only a single variation, and no control group. Label all these campaigns with a single GET-ALL-TEMPLATES selector group.
Set this sync to run at your desired frequency (we recommend every 5 minutes). Each run syncs your cache by calling a /choose call (like the one in the example) with this selector group, fetching all new templates from the CDN and caching them and any token not in the response can be removed from the cache.

curl --request POST \
  --url https://dy-api.com/v2/serve/user/choose \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'dy-api-key: your-api-key' \
  --data '{
    "selector": {
      "names": [],
      "groups": ["GET-ALL-TEMPLATES"]
    },
    "user": {},
    "session": {},
    "context": {
      "page": {
        "type": "HOMEPAGE",
        "location": "https://your.site.url",
        "data": []
      },
      "device": {}
    },
    "options": {
      "isImplicitPageview": false,
      "isImplicitImpressionMode": false,
      "returnAnalyticsMetadata": false
    }
}'