Experience APIs Implementation Guide

The following is the information you need to implement Experience APIs and start running campaigns. It's vital that you ensure a full and correct implementation before starting to run production campaigns. This guide presumes that you are using our DYID to refer to the user who visits the site or app. If you are planning an API-only implementation with user IDs generated on your end, skip to this section.

Before you start:

• If you are planning to implement the Dynamic Yield script on your website and have not yet done so, do that first, and then come back to this guide.  

• Make sure your Product feed is up and running.

  A product feed is a file that contains your product catalog (all your products, with product metadata). It powers affinity-based personalization, product recommendations, social proof messaging, and more. 

  You can create and sync your product feed in the Experience OS console using a data file or using APIs. 

Step 1: Generate API keys

Create API keys for your application.

If you want to call the API directly from the client side, either use a client-side API key or alternatively have your server-side act as a proxy for the client, so that it performs all reporting on behalf of clients. This latter option does involve more work, but is actually quite popular: It plays well with centralizing the reporting of user actions to multiple downstream systems, and with hiding implementation details and keys from the client.

Step 2: Make a Choose call to get campaign variations

All your campaigns must have an API Selector Name that you'll use in your Choose API call to get the variation you want. 

The response will include the necessary product data for recommendation campaigns, or variations for custom code campaigns. In addition, Dynamic Yield will send DecisionID or SlotID (for custom code or recommendation campaigns, respectively) attributes that you, in turn, report to us in the Engagement API call if the user clicks on a campaign.

Step 3: Add user and session IDs to your API requests

This is done using Dynamic Yield cookies. Add cookies like dyid, _dyid_server, and dyjsession into your API call so that Dynamic Yield can recognize the user.

Cookies are written by Dynamic Yield when the scripts are uploaded. If you send a Choose request for a page on which the scripts aren't running, and the user doesn't have an existing user and session IDs from previous pages, you should send us empty values, and we'll generate new user and session IDs and send them back.

Note that if you have Active Cookie Consent mode enabled, you must include the active_consent_accepted parameter. For more information, see Active Cookie Consent Mode for User Data Privacy Management.

Learn more about Dynamic Yield server-side cookies and how to implement them. 

Step 4: Report events 

Report any meaningful action that a user takes on your site or app. This typically includes cart and purchase operations for e-commerce, initiating and submitting applications for financial institutions, video views in the world of media, and any other events customized to your needs. Use these insights later, for behavioral targeting, reports, and more. Note that if you only report events from your server side, it is easier to avoid "noise" generated by bots and such.

Learn more about reporting events.

Step 5: Track and report user engagement with variations

As part of running API campaigns on the page, you should store the unique identifiers returned in the response from the Choose call. This is typically done on the client side. When a user then clicks on a variation or a specific recommended product, you'll need to pass these identifiers back to us.

• For a click on a custom-code variation, this would be the decisionId (and also the variationIds only in case of multi-variation campaigns such as sliders).
• For a click on a recommended item, this would be the slotId.

On the web, it is common to store these as data attributes on the DOM element that is rendering the variation, for example, <div id= ... data-dy-decision-id="d512ae8f">.

Set up on-click listeners on all rendered variations and report any clicks to Dynamic Yield, using the unique identifiers provided. This step is almost always initiated from the client side but can be proxied from your server side to our API to avoid having too much logic (or keys) in clients.

Learn more about reporting user engagement.

API-only implementation

User and session identifiers

With implementation on an API-only section type, you need to decide which user & session identifiers to use. Are there already such identifiers in your application that can be reused? What is their time-to-live and does it match your expectations?

If unsure, see our Best Practices. 

Tracking pageviews

In an API-only section type, you must report a new pageview for all pages across your site. For minimal latency, this is usually done together with fetching the chosen API campaign variations for that page, in one roundtrip to our Choose API endpoint.

Integrate a Choose call in all page types in your application with the proper page context, even without referring to any campaign yet.

Enabling preview support

While not technically required, we strongly recommend that you also add the code to support previewing content straight from the Experience OS console.