- 6 Minutes to read
Server-to-Server Implementation v1.0
- 6 Minutes to read
Abstract
Describes Yahoo Ad Tech’s new Enhanced Attribution implementation and outlines how the feature works, end-to-end, with step-by-step instructions for activating and operating this solution.
Overview
Given the current state of the industry, third-party cookies may no longer be available for advertising purposes, owing to increased online privacy regulations and additional tracking protections implemented by browsers and other devices. The blocking of cookies will limit conversion measurement and attribution for both browsers and devices.
Yahoo Ad Tech’s Enhanced Attribution solution mitigates the lost conversion attribution on browsers and devices through the use of a click ID as an identifier instead of a cookie or device ID.
This solution enables tracking of conversions that can work without identity synchronizations and also puts advertisers in control of monitoring the performance of their ad buys. The mechanism can provide post-click attribution for advertisers, and is available for the Yahoo DSP ad platform campaigns, as well as for Yahoo Preferred Network (Native Marketplace) campaigns.
How It Works
Enhanced attribution works by using a click ID as an identifier when browsers or devices block third-party cookies. Once you enable this mechanism, a Yahoo Ad Tech click ID macro (${CC}
) is added to the click-through URL, and is expanded with a unique value for that click.
To activate this feature (i.e., passing the click ID), code is appended to ad tags or click trackers that includes the parameter vmcid
= and a click ID macro "${CC}
.
The process flow is illustrated below:
The vmcid
parameter and the click ID pass these values to the landing page URL, which includes a Dot JavaScript tag after a user clicks on an ad. The vmcid
click ID is then captured by the Dot JavaScript tag on the page; then stored in the site’s first-party cookie and the browser’s local storage until the user eventually converts on the site within the lookback window controlled by the browser. (Currently, this lookback window is 24 hours for first-party cookies and seven days for local storage.)
Upon the conversion event, the vmcid
click ID is then passed back to the Yahoo DSP or Yahoo Native for attribution.
Important
Identity Enhanced Attribution adheres to all privacy regulations because the click event is not tied back to a user but instead only connects the conversion to a click event.
A server-to-server integration with Yahoo Ad Tech is performed by sending the click ID value from a landing page when a conversion happens.
Important
Server-to-server integration requires OAuth 2.0 authentication, which is described in the sectins below. Once the authentication is successful, the click ID-based conversions can be received on the following endpoint:
https://aaca.yahooinc.com/ --data "id=id123&vmcid=${INSERT_VMCID_COLLECTED_FROM_CLICK}&dp=simple_dp&gv=1
The supported parameters in the URL are described in the table below.
Integration Process
The integration process and flow is outlined in the steps below:
1 - Authentication
To take advantage of this solution, you must authenticate using OAuth 2.0. See the important note below for a link to Authentication requirements.
2 - Conversion tracking implementation
Once authentication is implemented, attributed conversion data can be posted to the endpoint as the advertisers or partners system generates the attribution data. To pass data to the endpoint, follow the conversion tracking implementation steps outlined in the section below.
3 - Data flow
Once conversion data begins flowing, data posted to this endpoint will be reportable in Yahoo DSP and Native ad platforms as a conversion metric. This data will flow into CPA optimization and will also power conversion metrics such as dynamic conversion values and ROAS.
The process flow is illustrated below:
The vmcid
parameter and the click ID pass these values to the landing page URL, which includes a Dot JavaScript tag after a user clicks on an ad. The vmcid
click ID is then captured by the Dot JavaScript tag on the page; then stored in the site’s first-party cookie and the browser’s local storage until the user eventually converts on the site within the lookback window controlled by the browser. (Currently, this lookback window is 24 hours for first-party cookies and seven days for local storage.)
A server-to-server integration with Yahoo is performed by sending the click ID value from a landing page when a conversion happens.
Important
Server-to-server integration requires OAuth 2.0 authentication, which is described in Authentication. Once the authentication is successful, the click ID-based conversions can be received on the following endpoint:
https://aaca.yahooinc.com/ --data "id=id123&vmcid=${INSERT_VMCID_COLLECTED_FROM_CLICK}&dp=simple_dp&gv=1
The supported parameters in the URL are described in the table below.
Known Limitations
Segmentation
There is no capability to segment exposed users or clickers for use cases such as retargeting, exclusion, or lookalike modeling.
Data uploads
At this time, this solution only supports API upload; there is no batch upload mechanism currently available.
Reporting time
All conversion attributions are reported at upload time, not conversion time or impression/click time.
Conversion Tracking Implementation
Creative instrumentation
Update tracker or click URLs to include the relevant macros to pass along the ID to the advertiser tracking systems. Other macros available are documented at https://developer.yahooinc.com/dsp/docs/macros/macros.html.
Examples:
Click Tracker Description | Example URL |
---|---|
Generic example | https://advertiser.clickserver.com?vmcid=${CC}&measurement_partner_required_param_A=${relevant_macro}&measurement_partner_required_param_B=SOME_FIXED_VALUE&……..INSERT OPTIONAL PARAMS……. |
Branch IO | https://branchster.app.link/EXAMPLE_BRANCH_APP_ID?$3p=a_vm_network&~click_id=${CC}&~secondary_publisher_id=${pubid} |
Implement a process or script to collect this ID value and associate it with your conversion data.
Rules setup
To ensure that this ad spend is measured by Yahoo Ad Tech’s attribution system, create a conversion rule for the Yahoo DSP line.
Conversion data postback
Once the conversion data is available, fire it to Yahoo Ad Tech’s API:
For example:
a) curl --tlsv1.2 -w %{http_code} https://aaca.verizonmedia.com/?id=id123\&vmcid=simple_click_id\&dp=simple_dp\&gv=10.0
b) curl --tlsv1.2 -w %{http_code} https://aaca.verizonmedia.com/ --data "id=id123&vmcid=${INSERCT_VMCID_COLLECTED_FROM_CLICK}&dp=simple_dp&gv=10.0" --header "Content-Type: application/x-www-form-urlencoded"
Required and supported parameters
The required and supported parameters are described in the table below:
URL Parameter Name | Description | Required? | Default | Example |
---|---|---|---|---|
vmcid | Value of the pixel context macro collected from the click or the third-party ad server. | yes | N/A | See the integration guide |
id | Unique event id provided by the partner identified in dp. This is a technical mechanism used by Yahoo Ad Tech to prevent duplication in reporting. | yes | N/A | Should be unique guids. Used to log the event for tracking. |
dp | The entity responsible for passing the data to Yahoo Ad Tech. | yes | N/A | “branch” |
et | Business Time of the Event (Epoch UTC milliseconds). | no | The receive time of the event is used if parameter is not present. | 1585604630466 |
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 and calculated as ROAS in Native. | no | None | 12.25 |
gc | Event Value Currency | no | None | |
ec | Event Category | no | None | |
ea | Event Action | no | None | |
.yp | pixel id | no | None | Maps to a pixel ID - if not provided then reporting will only be on the line/campaign level. |
Other parameters | no | N/A | Not to exceed name length of 32 nor value length of 255. |
API Return Codes
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 the initial release). | Invalid Authorization token. |
500 | Internal Server Error |
Additional Specs
Scenario | Message/Code |
---|---|
Users either put all of their KVs in the request body or put all of them in the query parameters (not split between them). | If both are provided, the body is processed only. |
If KVs are provided as ‘query parameters’, Content-Type must be “application/x-www-form-urlencoded” if specified | Else it will send code 400 (Error. Unsupported Content-Type.) |
If KVs are provided in ‘request body’, Content-Type must be “application/x-www-form-urlencoded” | Else it will send code 400 (Error. Unsupported Content-Type for request body.) |
Keys and Values must be encoded for both “query parameters” and “request body”. | Else it will send code 400 (Error. Request does not match specs.) |