Yahoo Pixel API
  • 9 Minutes to read

    Yahoo Pixel API


      Article summary

      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 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

      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 supported 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=yah

      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 observe 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 accesstoken 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


      Was this article helpful?