Recommendations Campaigns for Experience APIs Sites

Recommendations allow you to automatically display the most relevant items to each user. This article guides you on how to implement a recommendation widget using our server-side Experience APIs. The process includes:

1. Creating an API recommendation campaign in the Dynamic Yield console.
2. Calling the campaign with a server-side API call. The widget is rendered on your site.

Optionally, you can use real-time filters in your API recommendation campaigns. 

After you set up and run your API campaigns, you can then also:

1. Get a report of the clicks on your campaign. 
2. Validate your implementation.

Create an API recommendation campaign

Go to API Campaigns › Add New › Recommendation and do the following:

1. Give your campaign a name, and optionally, add notes and labels.
2. Specify the API Selector. This selector is needed in API calls to the campaign. 
3. Set the targeting settings of the experience to determine when, where, and for whom the experience is displayed, and then click Next. 
4. Create a variation. This is the recommendations settings, and it is called  variation because you can test multiple settings, or test it against a control group:
   1. Give your variation a name (only visible inside the Dynamic Yield console).
   2. 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.
   3. When creating the variation, you can also choose the strategy and number of items.
   4. When you are done with each variation, click Save Variation.
5. Set the allocation, primary metric, and advanced experience settings.
6. Define how much of your traffic to allocate to each variation and to the control group.
7. Click Save Experience. 
8. To create an additional targeted experience (say, different strategies for a different audiences), click the plus icon .
9. Click Save and Publish when you are ready to proceed.

Call 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 

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);
});

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": {
   "dyid": "dyid12345678",
"dyid_server": "dyid12345678"
 },
 "session": {
   "dy": "session12345678"
 },
 "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 

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. 

Use cases

Include specific SKUs

A typical use case is to request recommended products that fall within a specific price range. In this example, filter for products priced between $3,000 and $4,000. Code example

"id": "0000000000015000"
}
"sessionld" : "1"
"selector": {
    "names": [
        0 : "Popularity Campaign"
    ],
    "args": {
        "Popularity Campaign": {
            "realtimeRules": [
                0 : {
                    "type" : "include"
                    "slots" : []
                    "query" : {
                        "conditions" : [
                            0 : {
                                "field" : "price"
                                "arguments" : [
                                    0 : {
                                        "action" : "GT"
                                        "value" : "3000"
                                    }
                                ]
                            }
                            1 : {
                                "field" : "price"
                                "arguments" : [
                                    0 : {
                                        "action" : "LT"
                                        "value" : "4000"
                                    }
                                    

SKUs-only for Recommendations API campaigns

To reduce the size of the response, you can limit the response to only include the SKUs. SKUs-only request example

{
    "user": {
        "id": "yaexono4ohphania"
    },
    "session": {
        "custom": "iquahngaishe2koh"
    },
    "selector": {
        "names": [
            "recs campaign"
        ]
    },
    "context": {
        "page": {
            "type": "PRODUCT",
            "data": [
                "7383723-010"
            ],
            "location": "https://example.org",
            "locale": "en_US"
        },
        "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"
        },
        "pageAttributes": {
            "customPageAttribute": "someValue"
        },
        "options": {
            "isImplicitPageview": true
        }
    },
    "options":{
         "recsProductData": {
                "skusOnly": true
            }
    }
}

SKUs-only response example

{
        "sku": "1253557-035",
        "productData": {},
        "slotId": "l4WkdHl"
},

Using the fieldFilter parameter for Recommendations API campaigns

Certain use cases require getting additional fields, rather than just the SKU. However, you might require receiving some (but not all) fields. For this purpose we support specifying the fields you need using the “fieldFilter” parameter. Simply send an array of strings of the relevant fields, and only those fields and values are sent back. Note that if your API call also includes the “skusOnly”: true parameter, it overrides the “fieldFilter” parameter. 
As such, the response includes only the SKU and no additional fields. Text

{
    "user": {
        "id": "yaexono4ohphania"
    },
    "session": {
        "custom": "iquahngaishe2koh"
    },
    "selector": {
        "names": [
            "recs campaign"
        ]
    },
    "context": {
        "page": {
            "type": "PRODUCT",
            "data": [
                "7383723-010"
            ],
            "location": "https://example.org",
            "locale": "en_US"
        },
        "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"
        },
        "pageAttributes": {
            "customPageAttribute": "someValue"
        },
        "options": {
            "isImplicitPageview": true
        }
    },
    "options":{
         "recsProductData": {
                "fieldFilter": ["FieldName1", "FieldName2"]
            }
    }
}

Include specific SKUs

A typical use case is to request recommended products that fall within a specific price range. In this example, filter for products priced between $3,000 and $4,000. Include specific SKUs example

"id": "0000000000015000"
}
"sessionld" : "1"
"selector": {
    "names": [
        0 : "Popularity Campaign"
    ],
    "args": {
        "Popularity Campaign": {
            "realtimeRules": [
                0 : {
                    "type" : "include"
                    "slots" : []
                    "query" : {
                        "conditions" : [
                            0 : {
                                "field" : "price"
                                "arguments" : [
                                    0 : {
                                        "action" : "GT"
                                        "value" : "3000"
                                    }
                                ]
                            }
                            1 : {
                                "field" : "price"
                                "arguments" : [
                                    0 : {
                                        "action" : "LT"
                                        "value" : "4000"
                                    }