- 9 Minutes to read
Yahoo Pixel API Specification v1.0
- 9 Minutes to read
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 displayed 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
Refer to 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 |
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 view 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.
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’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:
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