Product Recommendation API for DPA Integration

This API product recommendation describes the 3rd-Party (3P) and Yahoo DSP API integration process and workflow for Dynamic Product Ads (DPA). The DSP API acts a proxy and forwards the request to the Native (YPN) API for this use case.

The goal of this effort is to provide advertisers with a list of product recommendations for a specific user using this API endpoint:

https://recommendation.admanagerplus.yahoo.com/userrecommendation

Static Setup

As part of identity matching, the following sequence will occur:

  1. The 3P will provide the domain name + the network path (if needed) for DSP to send:

  • Encrypted Yahoo user id as an id parameter.

  • Status of the User as a status parameter.

    • ok (Existing User)

    • notfound (New User)

    • error_{http_code} (Erroneous) and id parameter value (user id) will be empty in this case.

  1. DSP will store the following mapping:

  • Partner_id => DOMAIN_NAME

Runtime Calls

The sequence of runtime calls, which is part of identity matching, is described in the steps below:

Step 1

A 3P 1x1 image pixel will call one of these urls:

https://cms.analytics.yahoo.com?partner_id=ADVERTISER&otherQueryParam from https pages
http://cms.analytics.yahoo.com?partner_id=ADVERTISER&otherQueryParam from http pages

Step 2

DSO will redirect the HTTPS 302 with the location.

{PROTOCOL}://{DOMAIN_NAME}?id={USER_ID}&status={STATUS}&{QUERY_PARAMS}

Parameter definitions:

  • PROTOCOL is http or https, depending on the call coming from http or https.

  • DOMAIN_NAME is the domain name provided by 3P as part of the setup.

  • USER_ID is an encrypted OATH user id.

  • STATUS is

    • ok for an Existing User

    • notfound for a New User

  • QUERY_PARAMS are the other runtime parameters passed by the 1x1 image pixel. There is a cap of 2K size, and if the size exceeds that cap, then DSP will return error_{http_code} as status.

Illustrated Runtime Sequence

The following technical diagram describes the sequence of runtime calls for identity matching for a Yahoo dot tag.

Workflow #1

The 3P will have a 1x1 pixel on its website. This pixel will be fired when the user visits a specific page. On firing, the pixel makes a call to a Yahoo CMS server, with a specific partner ID that is specific to 3P. Yahoo makes a redirect call to the browser with the location specified as 3P servers.

Through this mechanism, Yahoo passes its encripted user ID to 3P with the status defined as either an existing user or a new user.

User Sync example 1x1 pixel

User Recommendation

As specified, 3P will provide its own recommendation for the user. The user could be either a mobile or web user.

Workflow #2

In this workflow, 3P will provide a recommendation for the corresponding Yahoo user.

User Recommendation

Fields

The following table lists the fields required to work with user recommendations for DPA integration.

Field

Description

Data Type

Required

userId

The userId issued by Native or IDFA for iOS or GPS ADID for Android.

string

YES

userIdType

  • WEB if the userId is provided by Native identity matching.

  • MOBILE if coming from the mobile device.

string

YES

lineId

The DSP line ID.

long

required

bidModifier

The Relative bid boost. The supported range is - 0.1 to 10.0.

double

YES

productIds

The List of recommended products for the user. It can be any number; however, the first one will be used for single ad display and the first 3 to 5 will be used for carousel ad display.

list<string>

YES

expiryDate

SO‑8601 format. Examples:

  • 2017-12-14T08:00

  • 2018-01-10

  • Maximum supported date is 30 days.

  • Timezone is UTC.

string

NO

status

ACTIVE/PAUSED. Defaulted to ACTIVE if not present in the payload.

string

NO

Note

Batch size is restricted to 2K.

Endpoint

Resource URI

https://recommendation.admanagerplus.yahoo.com/userrecommendation

Operations

Create a new user recommendation

Method: To create a new user recommendation, make a POST call to the user recommendation endpoint with the required fields.

Request

https://recommendation.admanagerplus.yahoo.com/userrecommendation

Data passed

{
        "userId": "6CFE688F-908F-41CF-BAF6-AC656257A886",
        "userIdType": "MOBILE",
        "lineId": 2196111,
        "bidModifier": 1.3,
        "productIds": [
            "def"
        ]
    }

Response:

Success:

{
    "errors": null,
    "timestamp": "2022-08-04 17:43:19",
    "response": [
        {
            "productIds": [
                ""
            ],
            "userId": "6CFE688F-908F-41CF-BAF6-AC656257A888",
            "bidModifier": 1.5,
            "adGroupId": null,
            "userIdType": "MOBILE",
            "expiryDate": 1661817600000,
            "status": "PAUSED",
            "advertiserId": 22750,
            "deviceType": null,
            "lineId": 2196111
        }
    ]
}

Failure:

{
    "errors": [
        {
            "code": "E40000_INVALID_INPUT",
            "message": "Invalid user id",
            "description": "",
            "errIndex": 0
        }
    ]
}

Read specific user recommendation data

Method: To retrieve data for a user recommendation, make a GET call with the userId parameter.

https://recommendation.admanagerplus.yahoo.com/userrecommendation?userId=6CFE688F-908F-41CF-BAF6-AC656257A888&userIdType=MOBILE

Response: The user recommendation associated with the user Id:

{
    "errors": null,
    "timestamp": "2022-08-04 17:38:52",
    "response": [
        {
            "productIds": [],
            "userId": "6CFE688F-908F-41CF-BAF6-AC656257A888",
            "bidModifier": 1.3,
            "adGroupId": null,
            "userIdType": "MOBILE",
            "expiryDate": 1661817600000,
            "status": "PAUSED",
            "advertiserId": 22750,
            "deviceType": "ALL",
            "lineId": 2196111
        }
    ]
}

Note

The PUT and DELETE operations are not supported.

To stop a recommendation, use POST with status = PAUSED.

For the user recommendations to serve, create a line with Audience Strategy = ADVERTISER_RECOMMENDATION

An example of a line with dpaAudienceStrategyType = ADVERTISER_RECOMMENDATION

{
    "response": {
        "id": 2226889,
        "name": "DPA Demo Line2: Advertiser Recommendation",
        "orderId": 433451,
        "bidPrice": 0.1,
        "goalAmount": 0.1,
        "billingPrice": 50.0,
        "completionThreshold": 0.0,
        "isNativeEnabled": true,
        "packageId": 82404,
        "channelType": "DEFAULT",
        "objective": "DYNAMIC_PRODUCT_ADS",
        "productSetId": 31266000,
        "isDpaEmailPromotionEnabled": false,
        "status": "PAUSED",
        "pacingModeType": "EVEN",
        "mediaType": "DISPLAY",
        "goalModeType": "HARD",
        "goalType": "ENHANCED_CPC",
        "billingMethodType": "CPC_WITH_MARGIN",
        "marginType": "TOTAL_BUDGET",
        "budgetType": "CURRENCY",
        "schedules": [
            {
                "id": 2275062,
                "budget": 10.0,
                "startDateStr": "2022-08-26T07:00:00Z",
                "endDateStr": "2022-09-30T06:59:59Z",
                "dailyBudgetType": "AUTO_ALLOCATED"
            }
        ],
        "feeList": [],
        "conversionList": [],
        "supplyType": "YAHOO",
        "language": "ENGLISH",
        "dpaAudienceStrategyType": "ADVERTISER_RECOMMENDATION"
    },
    "errors": null,
    "timeStamp": "2022-10-05T19:22:33.221Z"
}