Dynamic Yield for Developers Hub

Welcome to the Dynamic Yield for Developers Hub. Here, you'll find comprehensive guides and documentation to help you start working as quickly as possible. Let's jump right in!

Get Started    

Implementation Walkthrough

In this page

Learn about the typical sequence of actions you should follow as a developer.

Prerequisites

Here are a few things which are normally done once, and then not often changed afterward:

  1. Decide on the user & session identifiers you will use. If you're unsure what these should be, please refer to Best Practices.

  2. Create API keys for your application. For making calls from client apps without the direct use of API keys from the client, you have a few choices:

    2.1 Generate a JWT for each client, preferably for each session - defining a TTL is recommended, but not mandatory. When using JWTs, make sure you have it stored on client-side for the lifetime of the token, or -

    2.2 Have your server-side act as a proxy for the client so that your server will do all reporting on behalf of clients. This plays well with centralizing the reporting of user events to multiple downstream systems from one place - the rough equivalent of using a Tag Manager in the client.

  3. Make sure your product feed is synchronized with Dynamic Yield.

Reporting Events

It is good practice to ensure you're reporting any new page rendered (aka location or screen) and important events before starting to run campaigns. This is crucial for building user audiences and running any campaigns later on.

  1. Report Important Events. This typically includes cart and purchase operations in case of eCommerce, video views in the world of media, and any other events custom to your needs. In order to further protect against any tampering on the client side, it is recommended to report important events such as purchases from the server side, if possible.

Choosing Campaign Variations & Reporting Pageviews

Reporting a pageview and choosing campaign variations needed for rendering that page are best done with a single call to the choose endpoint, for efficiency. Following that, you can call choose with slightly different parameters for any campaigns that can be fetched asynchronously after the page has rendered.

Typically, the implementation workflow looks like this:

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

  2. Along with the person or people responsible for creating and managing campaigns (be it Marketers, Product Managers, Merchandisers, or other relevant roles in your organization), identify the places in your application where Dynamic Yield-managed campaigns should run. Any campaign that you run has an API Selector Name that you'll use to get the chosen variation.

Now, adapt your call to choose in each page type to fetch the selected variations for all campaigns which are part of rendering that page. By default, that call also causes a new page view to be reported - all the needed context is in the request already!

Any subsequent calls to choose which are asynchronous should be made with "options": { "isImplicitPageview": false } in the request body.

For all you need to know on choose, [see the detailed guide](doc:reporting-pageviews.

So... no explicit pageview reporting?

Normally, pageview reporting is simply an implicit part of calling choose. However, there is also a dedicated pageview endpoint for cases where you only need the reporting without any campaigns and prefer to make it explicit. All page-related arguments are the same.

Tracking and Reporting User Engagement with Variations

  1. As part of integrating the chosen variations in the page (or running any other action that should happen as a result of a chosen variation), you should store the unique identifiers returned in the response from choose. This is typically done on the client side. When a user then clicks on a variation or a specific recommended item, you'll need to pass these identifiers back to us.

    • For a click on a custom variation, these would be the decisionId and the variationIds.
    • 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 tag that is rendering the variation, e.g. <div id= ... data-dy-decision-id="d512ae8f">.
  2. Set up on-click listeners on all rendered variations and report any clicks to Dynamic Yield using the unique identifiers you've stored. This step is almost always initiated from the client-side. However, you may decide to report the engagement to your server-side first, then have it report to us - which is a good fit to the "no API keys in client" option.


Further Reading

Creating Keys

Implementation Walkthrough


Suggested Edits are limited on API Reference Pages

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