Dynamic Yield Developer Documentation

Browse Dynamic Yield's latest developer documentation including API references, articles, and sample code for optimizing, personalizing, and creating consistent digital customer experiences across touchpoints.


Implementation Guide

Which Implementation Are You Going For?

First and foremost, you should decide on the implementation mode you will use - please refer to Which Implementation is Right for Me?.

It is very good practice to ensure a full and correct implementation before starting to run production campaigns. This includes firing pageviews across the application and reporting events and clicks. Here's how.

If You Chose an API-Only Implementation

With the API-Only Implementation, you should now settle on the user & session identifiers you will use. Are there already such identifiers in your application that can be re-used? What is their time-to-live and does it match your expectations?

If unsure, please refer to Best Practices. Example code for managing these IDs is also found in the
tutorial. Then, continue following this guide.

If You Chose to Use the API in a Web-Based Implementation

Go through the steps of implementing Dynamic Yield on the Web, as detailed in our Knowledge Base. Once done, you are ready to use any of our web-based tools. Now, continue down this list to start using the API as well.


  1. 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 will perform 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.

  2. Make sure your product feed is up and running.

Reporting Pageviews (API-Only Implementation)

In Hybrid Mode, once you've completed the standard web-based implementation steps (see above) there is nothing more you need to do for pageview reporting, as our client script collects pageview data automatically. Skip to the next section.

In API-Only Mode, however, you need to 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 pages types in your application with the proper page context - even without referring to any campaign yet.

Calling choose to Get Campaign Variations

Along with the business users in charge of managing campaigns in your organization - be it Marketers, Product Managers, Merchandisers, or other relevant roles, identify the places in your application where Dynamic Yield-managed campaigns should run. Any campaign that you run will have a known API Selector Name which you'll use to get the chosen variation.

In any page where you wish to run API Campaigns, add or adapt the call to choose to fetch the chosen variations for all campaigns relevant to that page.

For all you need to know on choose, see the detailed guide.


Calling choose asynchronously

Following the initial page rendering you can also asynchronously choose for any campaigns that can be displayed after the page has rendered (in particular, for visual elements below the fold). In such calls, make sure to set "options": { "isImplicitPageview": false } in the request body.

Reporting Events (API-Only Implementation)

Report Important Events. This typically includes cart and purchase operations in case of e-commerce, video views in the world of media, and any other events custom to your needs. Note that if you only report events from your server-side, it is easier to avoid "noise" generated by bots and such.

Tracking and Reporting User Engagement with Variations

As part of running API campaigns in the page, you should store the unique identifiers returned in the response from the choose API. 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 variation, that 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, e.g. <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 above. 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.

Enabling Preview Support

While not technically a must, it's really strongly recommended to do "one more thing" and add the code to support previewing content straight from the Admin UI.

Updated about a year ago

Further Reading

Creating Keys

Implementation Guide

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.