Yahoo Pixel API Specification v1.0

Abstract

Describes the design, access and use of the Yahoo Pixel API, which supports server-to-server posting of event data utilizing various identity keys. The specification includes examples, schemas and descriptions of use cases, enabling direct audience building and conversion tracking via the product.

Overview

The Yahoo Dot pixel is currently used for audience retargeting and conversion tracking via onsite pixel tracking. By default, pixels use cookies as the main identifier to communicate with Yahoo. The Yahoo Dot pixel does support enhanced identifiers such as hashed e-mail addresses and click IDs today.

With changes to consumer privacy regulations and advertisers moving to more centralized tracking and data organization technologies, as well as browser restrictions on the use of cookies, different methods and strategies for implementing and communicating audience information to Yahoo are needed.

The Yahoo Pixel API specification is intended to address these issues and provide a solution for advertisers. Instead of tracking onsite pixel events, clients’ servers will now be able to call the Yahoo API endpoint in order to send enhanced user identifiers along with event information.

Important

The Yahoo Pixel API supports identifiers that do not rely on cookies, leverage secure privacy protocols, and enable advertisers to have full control over the data sent to the platform.

How It Works

The end-to-end process for activating against the Yahoo Dot pixel API works as follows:

1. The client creates authentication credentials via an OAuth 2.0 connection, as explained in the section below.

2. Yahoo creates a new set of encrypted credentials for the client.

3. Yahoo and the client work together to generate an allow-list with a unique Pixel ID for the API POST call.

4. Yahoo and the client work together to create new rules in the Yahoo DSP that describe the targeting and/or conversion audience.

5. The client begins to POST events to the Yahoo Pixel API.

Endpoint Details

The specification shown below identifies the key components of the Yahoo Pixel ID including the POST url, header types and the POST body. A typical POST body requires an identity key (email, device ID) and custom data - which is a description of the event (revenue, data to segment an event into an audience)

Endpoint

https://dataxonline.yahoo.com/v1/pixels/{insert_pixel_id}/events

Note

See the section below for details on how to create a Pixel ID (yp ID) in the Yahoo DSP.

Method: POST

Headers

Content-Type: application/json

Accept: application/json

Authorization: Bearer <access_token>

POST body - JSON keys

[
        {
        "event_time": "", // Unix Timestamp in seconds for the time of event "action_source": "", // Source of event like Website or App or Offline "action_source_url": "", // URL of website
        "user_data": { // Enhanced user identifiers "email”: ““, // SHA-256 Hashed email value "gpsaid": “”, // Google Play Store Advertiser ID "idfa": “”,// Apple Advertiser Id
        “yahoo_id”: // Cookie Sync Identifier “vmcid”: "" // Click id (Not supported in V1)
        },

        "custom_data": { // Custom advertiser data
        "gv": "", // Monetary value
        "ec": "", // Category of the content associated with the event "el": "", // Lower level label under a category
        "ea": "", // Action defined by the advertiser, such as AddToCart "product_id": [], // Array of product ids for DPA support "user_defined": {} // User defined key-value pairs, max = 10
        }

    }
]

Required and supported parameters

The required parameters for a successful JSON body POST are described in the table below:

Note

The equivalent Yahoo Dot pixel equivalents are included for those who are migrating from a pixel to the API.

Sample Event

The following sample event would tie to an audience-building rule for a specific pixel ID built out in the Yahoo DSP.

In UI Pixel Rule

Pixel API Payload

{
        "event_time": "'"${timestamp}"'", "action_source": "WEBSITE", "action_source_url": "www.test.com",
        "user_data": {
        "idfa": "e5b50a8b-3a77-4f83-aff4-68aa167f7c67"],
        "vmcid": "p$g,o$96051f32-00a9-11e5-ae6b-ef933523f69b-7fa00a750700,t$2173541273654", "email": "17a6624c439a77854504c6987bee2a7fd2deb078aab26d48d051b2af70a4ea2f"
        },

        "custom_data": {
        "gv": "12.99",
        "ec": "test_category",
        "el": "test_label",
        "ea": "test_action",
        "product_id": ["product_id1", "product_id2"],
        "user_defined": {
         "addToCart" : "true",
             "signUp" : "true",
             "purchaseAmount" : "1500"
        }
}}

Output

{
"success": true
}

Create a Pixel ID (yp ID) in the Yahoo DSP

Important

If you are already using Yahoo Dot pixels, you’ll see this firing through the .yp parameter. Don’t use the same pixel ID that is currently in use on a site, so that you can keep clean tracking and avoid duplication.

Follow these steps:

1. Under your Advertiser in the DSP, navigate to the Tracking tab.

2. Click Create New and Pixel.

This generates the unique pixel ID that you can use to populate in the POST endpoint. You don’t need to place the pixel tracking code, but simply take the pixel ID from this to use it.

OAUTH 2.0 AUTHENTICATION

The Yahoo Pixel API is a server-to-server implementation that requires OAuth 2.0 authentication before any data can be posted to Yahoo Ad Tech servers.

OAuth 2.0 is a mechanism that relies on continuously generating authentication tokens and then providing those tokens during the posting of data. Note that Yahoo Ad Tech has no plans to support OAuth 1.0, which depends on static tokens.

Follow the steps outlined below to create your Client ID and Secret for secure authentication.

Request Client Credentials

Note

Requesting client credentials includes an internal allowlist approval process that may require additional time for the setup to be completed.

To complete the steps below, you first need a Client ID and a Secret. Follow the steps outlined below to request them.

1. Generate a private key.

   >> openssl genpkey -aes256 -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out private_key.pem

2. Generate a public key using the above private key.

   >> openssl rsa -in private_key.pem -out public_key.pem -outform PEM -pubout

3. Send the public key to your Yahoo representative.

4. Yahoo will then send a file containing credentials encrypted with the above public key for you to use.

5. Decrypt the file with the private key.

   >> openssl rsautl -decrypt -inkey private_key.pem -in credential.enc -out my_credentials.txt

   The authentication process is illustrated in the following diagram:

   

Post-Credential OAuth 2.0 Workflow

Once you’ve received your encrypted credentials from your Yahoo representative, follow these steps:

Step 1: The external provider calls the ID B2B server to get the access_token, which is valid for 60 minutes.

Step 2: Provider calls the POST /identity/oauth2/access_token endpoint of ID B2B with the JWT token created out of the provided client_id and the client credential.

Sample Request

curl -X POST 'https://id.b2b.yahooinc.com/identity/oauth2/access_token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer' \
--data-urlencode 'client_assertion=<jwt_token>' \
--data-urlencode 'scope=pixel-event' \

--data-urlencode 'realm=dataxonline'

Sample Response

{
  "access_token": "wcf1011c-70fe-4740-b8a1-781d2b4dd3q3",
      "scope": "pixel-event",
      "token_type": "Bearer",
      "expires_in": 3599
 }

Generating JSON Web Token (JWT)

The JSON Web Token is composed of three main parts:

1. Header: normalized structure specifying how the token is signed (generally using the HMAC SHA-256 algorithm).

2. Free set of claims embedding whatever you want: client_id, aud, expiration date, etc.

3. Signature ensuring data integrity.

The signature mechanism is HMAC_SHA256 as defined by the JOSE specifications:

https://tools.ietf.org/html/draft-ietf-jose-json-web-signature-31

JWT Header
{
"alg": "HS256",
"typ": "JWT"
}

JWT Claims
{

"aud": "https://id.b2b.yahooinc.com/identity/oauth2/access_token?realm=dataxonline,
"iss": "{client_id}",
"sub": "{client_id}",
"exp": {expiry time in seconds},
"iat": {issued time in seconds},
"jti": "{UUID}"
}

Note the following:

• “exp” and “iat” values should be numeric. Do not set them as strings.

• “exp” value is currentTime + 3600 (i.e. 60 minutes).

• Don’t use currentTime + (24 * 60 * 60). You may get a “JWT has expired or is not valid” error.

• UUID - A Universally Unique IDentifier, https://www.ietf.org/rfc/rfc4122.txt

Walking through manual steps to build this JWT value

jwt_signing_string = base64url_encode(jwt_header) + '.' + base64url_encode(jwt_body)

jwt_signature = base64url_encode(hmac_sha256(jwt_signing_string, client_secret))

JWT = jwt_signing_string + '.' + jwt_signature

You can find JWT libraries at https://openid.net/developers/libraries/.

Step 3: The client extracts the access_token from the response and makes calls to the DataX Real-Time API /v1/pixels/{pixel_id}/events with the access_token in the Authorization header.

Sample Request

curl -X POST \
    https://dataxonline.yahoo.com/v1/pixels/10157549/events \
    -H 'authorization: Bearer 9f4c74cf-5bb9-45ce-987c-e5240e5710b8' \
    -H 'cache-control: no-cache' \
    -H 'content-type: application/json' \

    -d '[
    {
    "event_time": "1632847109",
    "action_source": "WEBSITE",
    "action_source_url": "www.test.com",

    "user_data": {
    "idfa": "e5b50a8b-3a77-4f83-aff4-68aa167f7c67",
    "vmcid": "p$g,o$96051f32-00a9-11e5-ae6b-ef933523f69b-7fa00a750700,t$2173541273654",
    "email": "17a6624c439a77854504c6987bee2a7fd2deb078aab26d48d051b2af70a4ea2f",
    },

    "custom_data": {
     "value": "test_value",
     "ec": "test_category",
     "el": "test_label",
     "ea": "test_action",
     "product_id": ["product_id1", "product_id2"],
     "user_defined": {
            "addToCart" : "true",
            "signUp" : "true",
            "purchaseAmount" : "1500"
     }
    }}
      ]

Sample Response

{
"success": true
}

However, if the client access_token is not found in the cache, we will call the ID B2B server endpoint identity/oauth2/introspect.

Step 4: The API will verify the client access_token. It first checks if the client’s access_token in the header of the request is present in the ClientAccessToken cache. If found in the cache, we don’t call the IDB2B server for access_token verification. We check the value in the cache to find out if it is valid or invalid.

However, if the client access_token is not found in the cache, we will call the ID B2B server endpoint identity/oauth2/introspect.

• admin_access_token is the access token for DataX online API, which will be sent in the Bearer Authorization header.

• client_access_token is the access_token of the client or the external provider which has to be verified

Sample Response

{
"active": false
}

Step 5: The result of the client access_token introspection with ID B2B will be saved in the ClientAccessToken cache with the key as client access_token and the response from Id B2B server as the cache value. The cache expiration is 7 minutes.

Rate Limitation

A rate limit is the number of events that are allowed within an API call an advertiser can make within a given period.

• An advertiser can send up to five thousand events per second.

• No limit is currently set for the amount of an API calls an advertiser can make.

Error Responses

The following return codes can come back in response:

Document History

• Document version 1.0 released externally 11/30/2022