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:

The client creates authentication credentials via an OAuth 2.0 connection, as explained in the section below.
Yahoo creates a new set of encrypted credentials for the client.
Yahoo and the client work together to generate an allow-list with a unique Pixel ID for the API POST call.
Yahoo and the client work together to create new rules in the Yahoo DSP that describe the targeting and/or conversion audience.
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.

API JSON key	DOT pixel equivalent	Description	Required?	Example
event_time	n/a	Business Time of the Event (Epoch UTC milliseconds).	yes	1585604630466
Idfa gpsaid	mi	Mobile Identifier	no	AB1234CD-A567-89EF-G101-12ABC3D45678
email	he	SHA256 encrypted email. Source data must be lowercase; no spacing or special characters.	yes	A7A4DED2D5035ADB26A222C67032F04CFCD2279AB508CF2A7FF612AEAD97551E
vmcid	vmcid	Value of a click ID from a url macro collected from the click or third-party ad server. Note that this will be bsupported in V2 of the spec.	no	p$g,o$96051f32-00a9-11e5-ae6b-ef933523f69b-7fa00a750700,t$2173541273654
gv	gv	The numerical value of any given conversion. By default, the value is assumed to be USD. This will be reported as a dynamic conversion value in DSP.	no	12.25
ec el ea	ec el ea	Event Category Event Label Event Action Standard event description fields used to segment event into an audience when building a rule in the platform.	no	ec=Button el=Product_Demo ea=Purchase
product_id	product_id	Product ID or multiple IDs separated by comma delimiters.	no	P112345, P26789s
“user defined”	“user defined”	These are custom event labels that the client can custom name instead of the standard events described above. Not to exceed the name length of 32 nor value length of 255.	no	page_name=homepage sku=134567 source=yahoo

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:

Under your Advertiser in the DSP, navigate to the Tracking tab.
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

Generate a public key using the above private key.

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

Send the public key to your Yahoo representative.
Yahoo will then send a file containing credentials encrypted with the above public key for you to use.
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’v 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:

Header: normalized structure specifying how the token is signed (generally using the HMAC SHA-256 algorithm).
Free set of claims embedding whatever you want: client_id, aud, expiration date, etc.
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:

Code	Message	Reason
200	Submission processed.	Valid request
400	Error. Unsupported Content-Type.	Invalid Content-Type provided.
400	Error. Unsupported Content-Type for request body.	Request has body but no Content-Type provided.
400	Error. Missing body and no query parameters provided.	Missing query params and body.
400	Error. Request body/params formatting error.	Unable to parse request body/params. Failed to decode KVs in request body. Failed to decode KVs in query params.
400	Error. Request does not match specs.	Key longer than maximum 32 characters. Value longer than maximum 255 characters. Missing required field ‘id’. Missing required field ‘vmcid’. Missing required field ‘dp’. NumberFormatException for keys: et or gv.
401	Error. Invalid ‘Authorization’ HTTP Header. Request a new token. (Not enforced in initial release)	Invalid Authorization token.
500	Internal Server Error

Document History¶

Document version 1.0 released externally 11/30/2022