API Recommendation Campaigns for Apps – Dynamic Yield Knowledge Base

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:

Creating an API recommendation campaign in Experience OS.
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

In the App Personalization app, go to Campaigns › Create Campaign › API Recommendations and do the following:

Give your campaign a name, and optionally, add notes and labels.
Specify the API Selector. This selector is required in the API calls. Optionally, add an API selector group.
Set the page context in the Page Type field, and then click Next.
Give the experience a name, and then click New Variation.
Or, to base the variation on an existing one, click Copy From Another Experience.
You can have multiple variations for a recommendation campaign, which you can use to test multiple settings or test against a control group. To create a variation:
1. Give your variation a name (visible only in the Experience OS console).
2. Select 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 or the design definition.
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.
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 Next.
Set the targeting settings of the experience to determine when, where, and for whom the experience is displayed, and then click Next.
Set the experience status to Draft (default) or Active, and then click Save Experience.
To create an additional targeted experience (say, different strategies for different audiences), click the plus icon .
Click Save when you are ready to proceed.

Now you're ready to call your campaign using the Choose API call.

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"]
            }
    }
}