API Recommendations Campaigns for Web

Recommendations enable 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. View logs and troubleshoot.

Create an API recommendation campaign

Go to Web Personalization › Create 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 required in the API calls. 
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. You can have multiple variations for a recommendation campaign, which you can use to test multiple settings, or test against a control group:
   1. Give your variation a name (visible only in the Dynamic Yield console).
   2. Choose a template. The template enables you to add an additional payload to the call. This 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, and more.
   3. When you create the variation, you can also select the strategy and number of items to show.
   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 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": {
   "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);
});

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. 

Report Engagement

To report clicks on your campaigns to Dynamic Yield, use the Reporting Engagement API call.

For more details, see the API reference.  

View logs

Check out the API Logs to see a history of recent API calls, their status, and more. Use this information to make adjustments or troubleshoot as needed. 

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.

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 recommendation 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 campaigns

Some use cases require calling additional fields, rather than just the SKU, but maybe not all fields. Specify the fields you want using the fieldFilter parameter: Create 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, and the response includes only SKUs and no additional fields.

Filtered fields 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": {
                "fieldFilter": ["FieldName1", "FieldName2"]
            }
    }
}