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:
- Creating an API recommendation campaign in the Dynamic Yield console.
- 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:
Create an API recommendation campaign
Go to API Campaigns › Add New › Recommendation and do the following:
- Give your campaign a name, and optionally, add notes and labels.
- Specify the API Selector. This selector is needed in API calls to the campaign.
- Set the targeting settings of the experience to determine when, where, and for whom the experience is displayed, and then click Next.
- 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:
- Give your variation a name (only visible inside the Dynamic Yield console).
- 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.
- When creating the variation, you can also choose the strategy and number of items.
- When you are done with each variation, click Save Variation.
- Set the allocation, primary metric, and advanced experience settings.
- Define how much of your traffic to allocate to each variation and to the control group.
- Click Save Experience.
- To create an additional targeted experience (say, different strategies for a different audiences), click the plus icon
.
- 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
HTTP Method |
|
Headers |
|
Body Parameters |
|
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
HTTP Method |
|
Headers |
|
Body Parameters |
|
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"]
}
}
}