Adding Experience APIs to Your Client-Side Script Implementation – Dynamic Yield Knowledge Base

See also the API Reference: Choosing Variations

Making API requests

Before you get started, create an API Key, if you haven't already done so.

The use case

To understand how API campaigns work in tandem with web personalization campaigns (based on a script placed on your site), consider the following scenario.

Assume that you have a website with an existing script-based implementation of Dynamic Yield. The first use case you've decided to migrate into an API Campaign is your Hero Banner – that nice big creative at the top of your homepage, where you really want to ensure no flicker or delay.

So, you set up an API Campaign for this banner with a few variations you want to test. Let's give it the selector name "homepage hero banner".

When a user navigates to your home page, the user's browser makes a request for this page from your backend server. As part of page rendering, a call is made to our choose API to get the right banner variation for this user.

Cookies for returning users

If this isn't the first time this user is interacting with your website, the user should already have a few first-party cookies that were previously set by our client-side script – which is already embedded in the page. These cookies are:

_dyid: The unique user identifier generated by Dynamic Yield. Usually referred to as the DYID.
_dyjsession: The current session identifier generated by Dynamic Yield. Since this cookie has a short time-to-live, it probably won't exist anymore when this returning user begins this current visit.
Another cookie to note is _dyid_server: This cookie is set by your backend server as part of the standard web implementation. This is required since April 2020, to conform with Apple's latest ITP (Intelligent Tracking Prevention) revision that governs the use of cookies in their Safari browser. This cookie simply holds a copy of the value of the _dyid cookie. By having this cookie set from your first-party server, Safari allows it to have a longer expiration period. For more details, see Safari Intelligent Tracking Prevention Policy and DYID Retention.

The API call (code)

To get the right variation for our homepage hero banner campaign, here's how to call the choose endpoint:

/choose request body for a returning user

{
  "user": {
    "dyid": "1679843083476146043",
    "dyid_server": "1679843083476146043"
  },
  "session": {
    "dy": "a2719b4d6c4709128bf5f57a3bf3"
  },
  "selector": {
    "names": ["homepage hero banner"]
  },
  "context": {
    "page": {
      "type": "HOMEPAGE",
      "location": "https://shop.biz/",
      "locale": "en_US"
    },
    "device": {
      "userAgent": "Mozilla/5.0 (X11; Linux x86_64) Chrome/56.0.29",
      "ip": "54.100.200.255"
    }
  }
}

Learn more about choose in Choosing Variations and Pageviews.

Note the following in the request:

The user attribute is an object containing the values of both dyid and dyid_server, which you should get straight from the cookies dyid and dyid_server as passed by the user's browser. For a returning user, you should have either one or both these cookies available. If you only got one of them, that's ok as well – pass the one you have. If you got both, pass both (they should have an equal value). Now that you've let us know this is a returning user, our servers can apply targeting based on all we know of that user (audiences, affinity profile, and so on).
Similarly, the session attribute is an object containing a dy attribute, which you should fill with the value of the _dyjsession cookie, if available. If not, simply don't pass anything within session, and a new session ID is generated in the response.

New users

If the visitor is new to your site and interacting with it for the very first time, none of the above-mentioned cookies are available to your backend code. In this case, we request the campaign with the user and session arguments empty:

/choose request body for a new user

{
  "user": {
    "dyid": "",
    "dyid_server": ""
  },
"session": {
    "dy": ""
  },
"selector": {
    "names": ["homepage hero banner"]
  },
  "context": {
    "page": {
      "type":"HOMEPAGE",
      "location":"https://shop.biz/",
      "locale":"en_US"
  },
  "device": {
    "userAgent":"Mozilla/5.0 (X11; Linux x86_64) Chrome/56.0.29",
    "ip":"54.100.200.255"
  }
}

Getting the response and setting cookies

Whether the user is new or returning, this is what the response looks like:

Choose response

{
  "cookies": [
      {"name": "_dyid_server", "value": "16798430146043", "maxAge": "63072000"},
      {"name": "_dyjsession", "value": "a2719b4d6c470383f1bf3", "maxAge": "1800"}
  ],
  "choices": [
      "id": 5,
      "name": "homepage hero banner",
      "type": "DECISION",
      "decisionId": "aGVsbG8K",
      "variations": [
        {
          "id": 52,
          "payload": {
            "type": "CUSTOM_JSON",
            "data": {
              "key1": "value1",
              "key2": "value2"
          }
        }
      ]
 ...
}

Note the cookies array in the response: Each entry has the exact name of a cookie you need to set as part of the response to the browser, along with its value and time to live (known as maxAge in the HTTP specification, in seconds). This array is not relevant in API-only mode.

Here are a few things to know:

Whether or not the user is new, you always get these cookies in the response, to set in your response. If you've passed these values in the request, you will get the same values back - but with an up-to-date maxAge. If you haven't passed them, new ones are generated and returned.
The expiry for the user ID is set for one year, and 30 minutes for the session. Since on each call to choose you get a fresh value, effectively this sets the length of user inactivity after which the browser should delete the cookies. Meaning, user IDs are "forgotten" after a year of inactivity, sessions end after 30 minutes of inactivity. For that to work correctly, always set the cookies you get back from the call to choose.

Going back to the use case scenario, after the user's browser receives the homepage along with the cookies, our client-side script embedded in the page knows to "respect" these cookies, so that the same identifiers are used for both API campaigns and web-based campaigns.

If the first-ever page that the user lands on does not use any API campaigns, these cookies are not available to the client script when the page loads. In this case, the script creates these cookies on its end.

As you might have already realized, a user making the second (or more) pageview even during their first-ever visit already has all the right cookies set, so for our purposes here they are already considered returning users.

See Choosing Variations and Pageviews for a detailed explanation of the choose endpoint.