Experience API Basics

Security

The API is HTTPS-only. Request and response bodies are JSON-encoded.

Authentication and authorization are based on API keys passed in the request header, which are managed through the Dynamic Yield console. You are highly encouraged to grant only the needed permissions for API keys and use dedicated keys when multiple components of your system need to interact with different parts of our API.

Data centers

Dynamic Yield works through two separate data centers to best support both latency and regulatory purposes. The data centers do not share any data between them, meaning that you must use only the API Gateway URL matching your account.

Note that the URLs are different for client-side and server-side API calls.

US data center

For server-side keys: 

Base URL: https://dy-api.com/v2/
Endpoint path example: https://dy-api.com/v2/serve/user/choose

For client-side keys: 

Base URL: https://direct.dy-api.com/v2/
For client-side collection endpoints: https://direct-collect.dy-api.com/v2/collect

EU data center

For server-side keys: 

Base URL: https://dy-api.eu/v2/ 
Endpoint path example: https://dy-api.eu/v2/serve/user/choose

For client-side keys:

Base URL: https://direct.dy-api.eu/v2/
For client-side collection endpoints: https://direct-collect.dy-api.eu/v2/collect

User and session IDs

Because we're all about personalization, it’s necessary that user and session IDs are defined correctly so that segmentation and experimentation run correctly. A user’s long-term behavior is very useful for targeting recurring users, while the proper session definition is important for session-length tests to run as expected, and for reports to show valid data.

• Generally, identifiers and their lifecycle are managed by Dynamic Yield. However, we still need you to pass and set the needed cookies. See the guide to using API and script together for more information.
  Although you need not generate or consider what the correct ID lifetime should be, it still pays to understand the purpose of each identifier, as explained in the following sections.
• If you are using the API-only implementation, with your own IDs rather the ones generated and managed by Dynamic yield, generating the IDs is totally up to you, as is storing these IDs for a duration that you control. 

User ID

The user ID identifies a single, unique device, whether the actual person using it is anonymous or known (logged-in or registered). This means that you're not expected to always have the ID of a known user account. Rather, you have a unique identifier value that is allocated when the device is first seen and stays persistent on that device for as long as is feasible.

In an API-only implementation, how you actually persist these IDs typically depends on the platform:

• On the web, this is usually done by setting a first-party cookie by your server. 
• For mobile apps, you can choose between various types of local data storage. In most cases, you already have such an ID. If you don’t, see the Best Practices article for guidelines. 

Session ID

The session ID represents a period of activity on a specific device and should only be valid for a limited time. This identifier usually already exists in your client apps. If not, see Best Practices for more information.

Core Experience APIs

The following are Experience API endpoints.

Choosing variations and reporting page views

Choosing Variations, or the Choose endpoint, is your primary endpoint. Using Choose, you receive the selected variations for one or multiple tests, regardless of the type of campaign. Custom campaigns, recommendations, and any other type of test are all served using this method, returning their appropriate payload in the response.

When a user navigates through your app, whether you render full web pages on the server side, or pass a JSON payload to your SPA or mobile app, it’s common to choose variations as part of the page rendering process. Our client script integrated into your website reports the pageview when loaded.

If you are using the Experience API without running the script on the page, the Choose call can also implicitly report a new pageview. Make sure to set this option to "true" in the API call (the default is false).

Pageview reporting is critical for many targeting conditions to work correctly, which in turn rely on the browsing history of the user – whether over time, in the current session, or on the currently-viewed page.

Choosing a variation need not happen only when rendering the page – and reporting a page view does not necessitate choosing a variation at that time. Choose can be called at any point during the lifecycle of a page, and is often called asynchronously for below-the-fold or dynamically loaded content. This helps keep the initial rendering of the page with minimal delay. For more information, see Best Practices.

For 95% of cases, we see a response time of 10-140 ms for Choose calls that include recommendation campaigns, and 10-30ms for Choose calls with custom campaigns without recommendations.

Reporting engagement with a variation

Now that you've received the chosen variations and rendered them (or performed any other relevant action), the next step is to get a report of the engagement with any rendered variation. For the sake of accurate reports, Dynamic Yield needs to record both impressions and clicks for each variation being served to the end-user.

• Impressions (when the user is exposed to a variation) are by default implicitly reported by the Choose call. (Note that changing this behavior to explicitly report impressions is possible. Contact us for more information.)

• Clicks always need to be reported by you. Unlike the client-side script loaded in the browser, in an API-based scenario, Dynamic Yield does not control or monitor the rendered content.
  Instead, the response from the Choose call contains identifiers for each unique decision made in that call. Store these identifiers, then pass them back when reporting a click. See Reporting Engagement.

Reporting events

Reporting meaningful user events (such as Login, Add to Cart, Purchase, Video Play, and so on) is crucial for both segmentation and experimentation: You typically want to target users based on their past actions or set an event as a primary or secondary metric for your campaigns. For more information about built-in and custom events, see Reporting Events.

In 95% of the cases, we see a response time of 5-25 ms for event reporting calls.

Rate limits

The Choose endpoint is globally limited to a rate of 22,000 requests per minute by default.
All other endpoints can be used with an unlimited rate of requests. When you reach your request limit, you get a status code of "429 - Too many requests" as your response. Contact your Technical Account Manager if your use case requires a different rate-limit enforcement configuration.