Recommendations Campaigns for Experience APIs Sites

Follow

Recommendations allow you to automatically display the most relevant items to each user. This article will guide you on how to implement a recommendation widget using our server-side Experience APIs. To do so, follow the following steps:

  1. Create an API Recommendation Campaign in the Dynamic Yield console
  2. Call the campaign with a server-side with an API call
  3. Render the widget on your site

Creating an API Recommendation Campaign

  1. Go to API Campaigns › Add New › Recommendation
  2. Give your campaign a name.
  3. Add notes and labels (optional).
  4. Specify the API Selector. This selector is needed in API calls to the campaign. 
  5. Set the targeting settings of the experience to determine when, where, and for whom the experience is displayed and click Next. 
  6. Create a variation. This is the recommendations settings, and it is called "variation" since you can test multiple settings, or test it against a control group.
  7. Give your variation a name (only visible inside the Dynamic Yield console).
  8. Choose a template. The template allows you to add an additional payload in addition to the recommendation. The payload can include any metadata you want to pass with the variation. For example, the title of the recommendation that matches the selected strategy, design definition, etc.
  9. When creating the variation, you can also choose the strategy and number of items.
  10. When you are done with each variation, click Save Variation.
  11. Set the allocation, primary metric, and advanced experience settings.
  12. Define how much of your traffic to allocate to each variation to the control group.
  13. Click Save Experience. 
  14. Click the plus icon icon_plus3.png to create an additional targeted experience (e.g. different strategies for a different audiences).
  15. Click Save and Publish when you are ready to go.
  16. Continue below with the procedures to call your campaign and track engagement. 

Calling the Recommendation Campaign with a Server-Side Call

In your app code, use DYAP.choose() to request a variation of a campaign.  

Path 

https://dy-api.com/v2/serve/user/choose 

HTTP Method
  • POST

Headers
  • dy-api-key: Your API key
  • content-type: application/json

Body Parameters
  • user - The User ID. The type of ID to use differs between API-Only Mode and Web Mode. In API-Only Mode, you are responsible for generating IDs for new users, and persisting them for existing ones. In Web Mode a Dynamic Yield-generated identifier is used, and managed via cookies.
    • id - The customer-supplied User ID. Required in API-Only Mode: Not supported in Web Mode.
    • dyid - Required in Web Mode: If the _dyid cookie exists, pass its value here. Otherwise, in case both this parameter and dyid_server are not passed, a new user ID will be created by Dynamic Yield and returned in the response. Not supported in API-Only Mode.
    • dyid_server - Required in Web Mode: If the _dyid_server cookie exists, pass its value here. Not supported in API-Only Mode.
  • session - The Session ID. The type of identifier differs between API-Only Mode and Web Mode. In API-Only Mode, the identifier is for you to generate & persist. In Web Mode, a Dynamic Yield-generated identifier is used.
    • custom - Required in API-Only Mode: the customer-supplied session identifier. Not supported in Web Mode
    • dy - In Web Mode, pass the value of the _dyjsession cookie if it exists. Otherwise, a new session identifier will be created by Dynamic Yield and returned in the response. Not supported in API-Only Mode.
  • sessionId - Deprecated. In pre-release versions of the API, this parameter was used for passing customer-managed session IDs. Please use the session parameter instead.
  • selector
    • names - Array of Dynamic Yield campaign names to choose variations for. Pass the API Selector Name of campaigns rather than the display name, which may change by the Admin UI User. Names are case-insensitive, but whitespace-sensitive. An empty list is valid.
    • preview - Preview token IDs, as passed by the dyApiPreview URL parameter on preview
      • ids - Array of preview tokens, as provided in the dyApiPreview URL parameter.
  • context 
    • page  - 
      • type - Page type, such as HOMEPAGE, CATEGORY, PRODUCT, etc.
      • data - Additional data related to the page type, such as the product SKU for PRODUCT-type pages.
      • location - Page URL (for web), location (for SPAs), or screen name (for mobile apps)
      • referer - Page referrer, if available. Optional.
      • locale - Page locale, such as "en_US". Optional.
    • Device
      • userAgent - For web-based clients, the User-Agent string. If not passed, the API Gateway will check for that header in the HTTPS request. Optional.
      • ip - The client IP address, for geolocation-based targeting and audience building. If not passed, the IP of the caller is used. Optional.
    • pageAttributes - A shallow object of custom attributes that can be used for campaign targeting in the Admin UI. Optional.
  • Options
    • isImplicitPageview - Set to false to disable implicit pageview reporting. Use this when calling choose more than once for a pageview. Boolean.
    • returnAnalyticsMetadata - Whether to return additional metadata (display names & IDs for all entities) useful for reporting to analytics tools. Boolean.
Node.JS Example

var request = require("request");

var options = {
  method: 'POST',
  url: 'https://dy-api.com/v2/serve/user/choose',
  headers: {'content-type': 'application/json', 'dy-api-key': 'your-api-key'},
  body: `{
  "selector": {
    "names": [
      "test1"
    ]
  },
  "user": {
    "id": "customUserId123"
  },
  "session": {
    "custom": "myCustomSession345"
  },
  "context": {
    "page": {
      "type": "HOMEPAGE",
      "location": "https://example.org",
      "locale": "en_US",
      "data":[]
    },
    "device": {
      "userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/56.0.2924.87 Safari/537.36",
      "ip": "54.100.200.255"
    }
  },
  "options": {
    "isImplicitPageview": false,
    " returnAnalyticsMetadata": false
  }}`
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

For more details, see the API reference. 

Reporting Engagement

Report clicks on your campaigns to Dynamic Yield using the following API call:

Path 

https://dy-api.com/v2/collect/user/engagement 

HTTP Method
  • POST

Headers
  • dy-api-key: Your API key
  • content-type: application/json

Body Parameters
  • user - The User ID. The type of ID to use differs between API-Only Mode and Web Mode. In API-Only Mode, you are responsible for generating IDs for new users, and persisting them for existing ones. In Web Mode a Dynamic Yield-generated identifier is used, and managed via cookies.
    • id - The customer-supplied User ID. Required in API-Only Mode: Not supported in Web Mode.
    • dyid - Required in Web Mode: If the _dyid cookie exists, pass its value here. Otherwise, in case both this parameter and dyid_server are not passed, a new user ID will be created by Dynamic Yield and returned in the response. Not supported in API-Only Mode.
    • dyid_server - Required in Web Mode: If the _dyid_server cookie exists, pass its value here. Not supported in API-Only Mode.
  • session - The Session ID. The type of identifier differs between API-Only Mode and Web Mode. In API-Only Mode, the identifier is for you to generate & persist. In Web Mode, a Dynamic Yield-generated identifier is used.
    • custom - Required in API-Only Mode: the customer-supplied session identifier. Not supported in Web Mode
    • dy - In Web Mode, pass the value of the _dyjsession cookie if it exists. Otherwise, a new session identifier will be created by Dynamic Yield and returned in the response. Not supported in API-Only Mode.
  • sessionId - Deprecated. In pre-release versions of the API, this parameter was used for passing customer-managed session IDs. Please use the session parameter instead.
  • Engagements - One or more engagements with a variation in an array
    • type -Set to CLICK for Custom Campaigns, or SLOT_CLICK for Recommendations 
    • decisionID - For a Custom Campaign, the unique Decision ID as returned from the choose endpoint. Not used for Recommendations.
    • variations- For a Custom Campaign, an array of one or more variation IDs the user interacted with, such as [45711, 49623]. Not used for Recommendations.
    • slotId - For a Recommendation Campaign, the Slot ID for the specific clicked item as returned from the choose endpoint.

For more details, see the API reference.  

Validating your implementation

Check out the API Logs to see a history of recent API calls, their status, and much more.