Experience API Basics

Security

The APIs are 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 in Experience OS. 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.

User and session IDs

Because we're all about personalization, user and session IDs must be defined correctly so 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 necessary 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 Dynamic Yield 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 channel:

• On the web, set a first-party cookie.
• For mobile apps, you can choose between various types of local data storage. In most cases, you already have such an ID. For API-type sections, see Best Practices to learn more.

Session ID

The session ID represents a period of activity on a specific device and is valid for a limited time. This identifier usually already exists in your client apps. For API-type sections, see Best Practices to learn more.

📌

Omni-channel user identification

To identify the same user across devices, you need to have another type of identifier, the customer unique ID (CUID) or a secondary identifier. Typically, this would be a hashed email or some internal ID from your backend systems. To learn more about associating User IDs with a CUID, 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.