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 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 CenterEU Data Center
Server-side keysBase URL: https://dy-api.com/v2/
Endpoint path example:
https://dy-api.com/v2/serve/user/choose
Base URL: https://dy-api.eu/v2/
Endpoint path example:
https://dy-api.eu/v2/serve/user/choose
Client-side keysBase URL: https://direct.dy-api.com/v2/
For client-side collection endpoints:
https://direct-collect.dy-api.com/v2/collect
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. 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 aren't using the Dynamic Yield script, generating the IDs is totally up to you, as is storing these IDs for a duration that you control.

User ID

The user ID (DYID parameter in the code) 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-type section 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.

📌

Omni-channel user identification

To identify the same user across devices, you need to have another type of identifier named Customer ID (CUID). Typically, this would be a hashed email or some internal ID coming from your backend systems. To learn more about associating User IDs with a Customer ID, see Reporting Events.

🚧

For mobile apps that have both WebView and native pages, make sure to:

  • Use the same user ID on all pages to make sure the user is considered the same user across pages.
  • Use the same session ID on all pages within a session. This is important for reporting and attribution.

Core Experience APIs

The following are the Experience API endpoints. See the API Reference for more details.

Choose: Choosing variations and reporting pageviews

Find a detailed overview in Choosing Variations. For technical details, see the API Reference.

The Choose endpoint is your primary endpoint, used to receive the selected variations for one or multiple tests. All campaign types are served using this method, returning their appropriate payload in the response. It's common to choose variations as part of the page rendering process as users navigate your app or site, and our client script on your website reports the pageview when loaded. If you use Experience APIs without running the script on the page, the Choose call can also implicitly report a new pageview.

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

For more information about reporting pageviews for pages without campaigns, see Reporting Pageviews and the API Reference.

Choosing a variation need not happen only when rendering the page – and reporting a pageview does not necessitate choosing a variation at that time. Choose can be called at any point during a page's lifecycle 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.

Engagement: Reporting user engagement with a variation

Find a detailed overview in Reporting Engagement. For technical details, see the API Reference.

After the chosen variations are rendered, you'll want a report detailing the user engagement. For accuracy, Dynamic Yield records both impressions and clicks for each variation.

Event: Reporting events

Find a detailed overview in Reporting Events. For technical details, see the API Reference.

Events are used to track meaningful user interactions (such as purchase, add to cart, form completion, or rating a product) and for behavioral targeting, building audiences, reporting, and recommendations.

There are predefined schemas for most common events, but you can also fire custom events as needed.