Dynamic Yield Developer Documentation

Browse Dynamic Yield's latest developer documentation including API references, articles, and sample code for optimizing, personalizing, and creating consistent digital customer experiences across touchpoints.


Previewing Content

:notebook-with-decorative-cover+: API Reference: Choosing Variations

How It Works With the Classic Implementation

With the classic implementation via a client-side script, preview works in a pretty straightforward fashion:

  • When you create a new variation in our Admin UI (or a new targeted experience, or a whole new campaign) you can click on the eye icon to preview and define over which page in your website to show that preview.

  • That webpage then opens in a new browser tab, with its URL modified by us to have a few more URL parameters specific to us. The client-side script detects these parameters and shows the previewed variation/campaign, without any special handling on your end. Voilà!

This is made possible as our script is running on your web pages. This method also applies to client-side experiments in Hybrid Mode and a similar solution is available in our Mobile SDKs for iOS and Android. However, when using the API (either API camping in a hybrid setup or API campaign in API only set up) there is no Dynamic Yield code on the page to do its magic, so how can preview be implemented easily?

How It Works With the API Campaigns

This is done in almost the same way as above, but requires a one-time extra integration step on your end as a developer:

  1. From the business user's perspective, they still have that eye icon for preview and click to define the webpage to preview on. Here's what it looks like:
  1. The specified webpage opens with an added URL parameter &dyApiPreview=<token>.

  2. As a developer, on any page where Dynamic Yield is integrated you should check for this URL parameter. If one exists, make sure to grab that token and pass it as an argument in your choose API call made from that page. Here's what the request body looks like:

  "user": { "id": "yaexono4ohphania" },
  "session": { "custom": "iquahngaishe2koh" },
  "selector": { 
     "names": ["PDP Top Banner", "PDP Recs"],
     “preview”: { // <== Here it is
        ids: [“preview-token-here”] 
   "context": { 
     // The usual context...

If the passed token is valid (tokens expire after 14 days) and refers to a variation in one of the campaign names passed in the selector > names argument, you will get the previewed variation content in the response - instead of the variation normally chosen for that campaign.

Look at the request above: assuming the preview token passed refers to a new unsaved variation in the PDP Top Banner campaign, here's what the response would look like:

  "choices": [
      "id": 245973,
      "name": "PDP Top Banner",
      "type": "DECISION",
      "isPreview": true, // <== Note this - preview was successful!
      "variations": [
          "payload": {
          "type": "CUSTOM_JSON",
          "data": {
            "title": "I'm a new variation yay!",
            "image": "new-variation-image.png"
      "decisionId": "mLM3Nzc1Nzc4MzNzU5YWE2NjA4"
    // Other campaigns...
  "warnings": [] // <== Only present if there are associated warnings

If the preview token is invalid - not found, has expired, or its campaign was not specified in the selector names, you will get a warning back in the warnings array attribute, such as:

  "choices": [
    // ... chosen variations for all selected campaigns
  "warnings": [
      "code": "W005",
      "message": "Requested preview id does not correspond to any requested campaign. Preview id: 7aa6608"

A missing preview should not fail the whole rendering of the page, and so the status code for the request is still 200, and for all selected campaigns we return the chosen variations.

Things to Note

  1. The preview attribute is in array notation mainly for future use. Currently, there is no feature in the Admin UI to preview multiple variations at once. However, you can manually collect multiple preview tokens and pass them as array in a single choose call.

  2. One important inherent difference from the client-side preview capability: to preview a variation, you must pass the selector name of the parent campaign in the standard selector->names attribute. That also means that the campaign itself must have been saved at least once, even when empty. If the preview token refers to a missing or unsaved campaign, you'll get a warning.
    While client-side campaigns support automatic insertion into a given selector in the DOM, with the API you as the developer are responsible for handling the display of all campaigns. An "orphan" preview variation could not magically inject itself into the screen.

  3. You can also ask for a preview already in the variation editor screen, while filling out the template fields:

  1. You can definitely share the resulting preview URL with colleagues as part of your content creation workflow, and it will function for them in the same way - regardless of whether they have access to our Admin UI. Since the token ID is randomly generated, it is not guessable by external actors, meaning that only those who have received a "legit" preview URL generated from the Admin UI are able to view that preview.

  2. An important note, particularly when sharing links: a generated preview link always returns the previewed variation content as "frozen in time", i.e. exactly as it was when the link was generated - regardless of any edits made later. If you're making updates and want to share those as well, create a new link. A given link always correlates to the same preview payload. As mentioned, links do expire after two weeks.

  3. If possible, aim to have the preview support in your code (detecting the URL parameter and passing it onwards to your call to choose) implemented in a single location in your codebase, so that it would take effect for all rendered pages.

More preview capabilities to come!

Updated 2 months ago

Previewing Content

:notebook-with-decorative-cover+: API Reference: Choosing Variations

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.