Client-side Recommendation APIs

Use the Dynamic Yield client-side recommendation APIs to request recommendation results without Dynamic Yield rendering them. The API returns product data in JSON format, so you control how the recommendation is rendered instead of serving it through an Experience OS recommendation campaign.

You can also #apply-real-time-filter-rules based on data collected during the current session. For example, you can request products priced higher than the currently viewed product or products that match a visitor's explicit selection.

Create a strategy to call via API

1. In Experience OS, go to Assets › Strategies.

2. Create or edit a recommendation strategy.

   

3. In the strategy settings, turn on Use via an API call (advanced) and enter the number of items to return.

4. Save the strategy.

In the Strategies page table:

1. From the strategy's More options menu, select Embed code, and copy the API snippet.

   

2. Edit the API as described in the following sections.

3. Paste the code into a Custom Code campaign to execute it for qualifying visitors.

4. To track recommendation performance, you must implement click reporting. For details, see #register-the-rendered-recommendation.

Request recommendation data

Use DYO.recommendationWidgetData() to request recommendation results for a strategy.

Syntax

DYO.recommendationWidgetData(id, opts, callback);

Parameters

id

The ID of the recommendation strategy.

Type: number

opts

An optional object containing the request configuration.

Type: object

The object supports the following properties:

callback

The function to run after Dynamic Yield processes the request.

Type: function

The callback receives the following arguments:

Example request

The following example requests recommendations for strategy 12345, excludes three group IDs, and provides a product page context:

DYO.recommendationWidgetData(
  12345,
  {
    exclude: {
      group_id: ["127829", "1217317", "1247581"]
    },
    context: {
      lng: "en_GB",
      type: "PRODUCT",
      data: ["1253851-001"]
    }
  },
  function (err, data) {
    if (err) {
      // Handle the error.
      return;
    }

    const recommendationData = data;
  }
);

Example response

The callback's data argument contains the recommendation response.

{
  "wId": 3197,
  "name": "TOP_N",
  "expData": {
    "varId": null,
    "expId": null
  },
  "fId": 543,
  "fallback": true,
  "slots": [
    {
      "item": {
        "entity_id": "330367",
        "sku": "6510120",
        "group_id": "33112327",
        "name": "tropical flower dress",
        "description": "the best tropical flower dress in the universe",
        "price": 199,
        "in_stock": true,
        "categories": [
          "women",
          "dresses"
        ],
        "url": "https://www.example.com/products/tropical-flower-dress",
        "image_url": "https://www.example.com/images/tropical-flower-dress.jpg"
      },
      "fallback": true,
      "strId": 1,
      "md": {}
    },
    {
      "item": {
        "entity_id": "330368",
        "sku": "6510145",
        "group_id": "33112347",
        "name": "tropical flower pants",
        "description": "the best tropical flower pants in the universe",
        "price": 89,
        "in_stock": true,
        "categories": [
          "women",
          "pants"
        ],
        "url": "https://www.example.com/products/tropical-flower-pants",
        "image_url": "https://www.example.com/images/tropical-flower-pants.jpg"
      },
      "fallback": false,
      "strId": 1,
      "md": {}
    }
  ]
}

Apply real-time filter rules

Use the realtimeRules property in the opts object to filter recommendation results based on data obtained during the current session.

For the supported rule structure and examples, see Return Recommendations Real-time Filter Data.

Register the rendered recommendation

After rendering the returned products, register the recommendation elements so Dynamic Yield can track their performance.

Syntax

DYO.recommendations.registerElements(el);

The el argument is the DOM element containing the recommendation widget.

Add tracking attributes

Add the response values to the rendered DOM elements:

<div
  data-dy-widget-id="3197"
  data-dy-feed-id="543"
>
  <div
    data-dy-product-id="6510120"
    data-dy-strategy-id="1"
  >
    <!-- Rendered product content -->
  </div>

  <div
    data-dy-product-id="6510145"
    data-dy-strategy-id="1"
  >
    <!-- Rendered product content -->
  </div>
</div>

Map the response properties to the DOM attributes as follows:

Register the element

After adding the widget and product elements to the DOM, pass the widget container to registerElements():

const widgetElement = document.querySelector(
  '[data-dy-widget-id="3197"]'
);

DYO.recommendations.registerElements(widgetElement);

Run this call after the recommendation elements are present in the DOM.

Get loaded recommendation widgets

Use DYO.recommendations.getLoadedWidgets() to retrieve the responses of all recommendation widgets loaded on the current page.

Syntax

DYO.recommendations.getLoadedWidgets();

Example

const loadedWidgets = DYO.recommendations.getLoadedWidgets();

The method returns an array containing the recommendation widget responses loaded on the page.