Server-to-Server In-app Events Specification v1.0¶
This specification describes the new Server-to-Server In-App events integration with the Yahoo Native API. The spec is intended for 3rd Party Mobile Measurement Providers (3PMMP) who wish to integrate with Native Ad Platform via S2S, and is aimed at Data Providers, like Kochava, AppsFlyer, Adjust, Apsalar, CyberZ/FOX and others.
The API will start accepting In-App events from verified 3P tracking partners. This enables partners to track post-install conversions and optimize advertiser campaigns for the signals that matter most.
For information about app install integrations, refer to the Server-to-Server App Install Specification v2.1.
Fields for In-app Events Endpoint¶
The following tables list the fields required to work with server-to-server in-app events integrations.
Key |
Description |
Values |
Type |
Code required |
Allow empty value |
---|---|---|---|---|---|
|
static hard-coded value |
Static value. Must be 8 |
int |
Yes |
No. Must be non-empty & valid. |
|
Native advertiser pixel ID, provided to 3rd parties from the advertiser. |
123456 |
int |
Yes |
No. Must be non-empty & valid. |
|
Native 3P provider ID, provided to 3rd Parties from Native contact. |
e.g., kochava |
string |
Yes |
No. Must be non-empty & valid. |
|
App store ID |
Android: com.yahoo.mobile.client.android.mail. iTunes: 577586159 |
string |
Yes |
No. Must be non-empty & valid. |
|
Google Ad ID, iOS IFA |
iOS IFA: 67247000-921f-41a1-ab22-b98b5071640f Google Ad Id: 38400000-8cf0-11bd-b23e-10b96e40000d |
string |
Yes |
No. Must be non-empty & valid. |
Key |
Description |
Values |
Type |
Code required |
Allow empty value |
---|---|---|---|---|---|
|
no |
Static value. Should always be no |
string |
Yes |
No. Must be non-empty & valid. |
|
Category of the event type |
|
string |
Yes |
No. The value cannot be empty per advertiser choice. Required when setting up a conversion rule. Because it is defined in the conversion rule, it must also be included in the request URLs in order for the MMP to see the claims. |
Key |
Description |
Values |
Type |
Code required |
Allow empty value |
---|---|---|---|---|---|
|
Name of specific event |
Valid values are:
|
string |
Yes |
No. Must be non-empty & valid. |
Key |
Description |
Values |
Type |
Code required |
Allow empty value |
---|---|---|---|---|---|
|
Additional event label |
[CUSTOM VALUE] |
string |
Yes |
Yes. The value can be empty per advertiser choice. |
|
Numeric data associated with the event |
[CUSTOM VALUE] |
Fixed point |
Yes |
Yes. The value can be empty per advertiser choice. |
|
Monetary value to track the conversion value. A number with fixed N positions (n=2) after the decimal point. |
4.50 |
string |
Yes |
Yes. The value can be empty/no value per advertiser choice. |
Key |
Description |
Values |
Type |
Code required |
Allow empty value |
---|---|---|---|---|---|
|
Country currency |
USD |
string |
Yes |
No. |
|
Self-attribution request id |
1234172534 |
string |
Yes |
No. |
|
In-app event time, in milliseconds |
1453497859 |
int |
Yes |
No. |
|
User Agent Info |
Key-value pairs of user agent identifying information. Format:
&ua=an%3Dcom.yahoo.frontpage%3Bav%3D5.3%3Bon%3DiOS%3Bov%3D10.2%3Bmk%3DApple%3Bmd%3DiPhone7%3Bsz%3D1224x750 See details on the supported keys in the table below. |
string |
Yes. Some keys that make up |
Yes. Some keys that make up |
Key |
Description |
Values |
Type |
Code required |
Allow empty value |
---|---|---|---|---|---|
|
Google referrer id |
Google install referrer value, without filtering.
This is based on the following Google Play store url: https://play.google.com/store/apps/details?id=com.blaze&referrer=utm_source%3Dko_2560575a034342ca7%26utm_medium%3DTumblr_BlazeStrike_SponsoredPage_Android_CPI_$20.00BlazeStrike%26utm_campaign%3Dkozz |
string |
Yes, if available. |
Yes, if not available. |
|
client IP address |
1.2.3.4 |
string |
Yes |
No |
|
client IPv6 address |
2001%3Adb8%3A85a3%3A8d3%3A1319%3A8a2e%3A370%3A7348 |
string |
Yes, if available |
Yes, if not available |
Note
Values should be url-encoded.
Request example¶
Self-attribution endpoint:
https://sp.analytics.yahoo.com/spp_sa
https://sp.analytics.yahoo.com/spp_sa?a=8&.yp=34093&dp=KCHVA&js=no&ai=com.yahoo.mobile.client.android.mail&mi=1234-4567-8790-1234&ea=Rated&ec=Engagement&gv=2.50&id=1234172534&gc=USD&et=1453497859&ua=an%3Dcom.yahoo.frontpage%3Bav%3D5.3%3Bon%3DiOS%3Bov%3D10.2%3Bdm%3DApple%3Bdo%3DiPhone7%3Bsz%3D4.7%3Bsd%3D1224x750&ir=utm_source%3Dko_2560575a034342ca7%26utm_medium%3DTumblr_BlazeStrike_SponsoredPage_Android_CPI_$20.00BlazeStrike%26utm_campaign%3Dkozzzo----android647b52ea521b6d2zxy6f3de374%26utm_term%3D%26utm_content%3D%26geminiPC%3DgTY5sk0f1HeiOKL1f.CqyzZmY7dfPREEfWTRWG8IyBiBFbYl6a8S9eAqXwrfsO__AUmjXBuV_onXMoNbCgVVvN3uwuFiyewMRMB8Sc9G1k_kABJuvRGl1_ZjiEELU8NBx_MnZzQ9hOL_g9gupuemqn_Vgkx3P_ygAGCUjE8mJeZlfuUDNoFWz1S5fFNnWLfWz67r0i_PHUB13FPxmdRnNvoEhDT56YDV_eFG1jRq..fVUPV5PTX7ZqqTf97&ip=1.2.3.4&ipv6=2001%3Adb8%3A85a3%3A8d3%3A1319%3A8a2e%3A370%3A7348
The ua
parameter key details, shown below:
User Agent Info Key |
Description |
iOS |
Android |
---|---|---|---|
|
App package name |
com.yahoo.frontpage |
com.appdeveloper.name |
|
App version |
5.3 |
4.75 |
|
OS name |
iOS |
Android |
|
OS version |
10.2 |
7.0 |
|
OS build |
NBD92B |
|
|
Device manufacturer |
Apple |
Motorola |
|
Device model |
Nexus 6 Data source: android.os.Build.MODEL |
|
|
Device name |
iPhone7,2 Data source: device.model from hw.machine See ‘Identifier’ column in https://www.theiphonewiki.com/wiki/Models for the example values. |
Shamu Data source: android.os.Build.DEVICE |
|
Device screen size (inches) |
4.7 |
5.66 |
|
Device screen dimensions (height x width) |
1334x750 |
2392x1440 |
Note
If any of key’s values contain special delimiter characters such as ‘=’ or ‘;’, please url-encode those key’s values.
Response JSON Schema¶
All fields listed below should be supported and consumed by the 3P data provider. Fields that are marked as optional, may or may not be sent in the response based on internal Yahoo Native availability.
Note
This is for the spp_sa self-attribution endpoint only.
{
"original_request": "string",
"claims": {
"type": "array",
"items": {
"type": "object",
"properties": {
"timestamp_ms": {
"type": "integer"
},
"event_type": {
"type": "integer"
},
"creative_id": {
"type": "integer"
},
"creative_name": {
"type": "string"
},
"adgroup_id": {
"type": "integer"
},
"adgroup_name": {
"type": "string"
},
"campaign_id": {
"type": "integer"
},
"campaign_name": {
"type": "string"
},
"advertiser_id": {
"type": "integer"
},
"advertiser_name": {
"type": "string"
},
"demand_platform_id": {
"type": "integer"
},
"campaign_type": {
"type": "string"
}
}
}
},
"network_id": {
"type": "string"
}
}
Response JSON Example¶
All fields listed below should be supported and consumed by the 3P data provider. Fields that are marked as optional, may or may not be sent in the response based on internal Yahoo Native availability.
{
"original_request": "https://...",
"claims": [
{
"timestamp_ms": 1445539353000,
"event_type": 200,
"creative_id": 1923847162,
"creative_name": "creative name",
"adgroup_id": 1324182736,
"adgroup_name": "ad group name",
"campaign_id": 302934875,
"campaign_name": "campaign name",
"advertiser_id": 908733,
"advertiser_name": "advertiser name",
"demand_platform_id": 1,
"campaign_type": "App Install"
},
{
"timestamp_ms": 1445539353001,
"event_type": 200,
"creative_id": 1923847163,
"creative_name": "creative name",
"adgroup_id": 1324182737,
"adgroup_name": "ad group name",
"campaign_id": 302934875,
"campaign_name": "campaign name",
"advertiser_id": 908733,
"advertiser_name": "advertiser name",
"demand_platform_id": 2,
"campaign_type": "Reengagement"
}
],
"network_id": "9128376dhfgasd"
}
Response field types and descriptions are shown in the table below.
Field |
Type |
Description |
---|---|---|
|
string |
Original app install request from 3P Data Provider. |
|
integer |
Event timestamp, in milliseconds. |
|
integer |
Event type: 100 = impression 200 = click 300 = app install |
|
integer |
Native creative (ad) id. |
|
string |
Native creative (ad) name. |
|
integer |
Native ad group id. |
|
string |
Native ad group name. |
|
integer |
Native campaign id. |
|
string |
Native campaign name. |
|
integer |
Native advertiser id. |
|
string |
Native advertiser name. |
|
string |
Attribution claim method: identifier, fingerprint, referrer. Note: This is an optional field (may or may not be returned). |
|
integer |
Id to allow measurement partner to determine which Yahoo Native demand platform served the claim. Note that 1 is for Native, 2 is for BrightRoll DSP. |
|
string |
Used to share different campaign objectives to 3P. Note that this is for App Install, Reengagement campaigns. |
|
string |
Id to identify Native to 3P Data Providers. Note that is an optional field. |
Headers¶
Client IP address should be sent through “X-Forwarded-For” header in HTTP request.
The general format of the field is:
X-Forwarded-For: client, proxy1, proxy2
Multi-Touch Attribution¶
When Multi-Touch Attribution is supported, the claims
array will contain multiple entries for all events that can be attributed to the in-app postback. The 3rd Party tracking partner will be able to determine the last touch
claim and other Multi-Touch Attribution events and present those appropriately to advertisers.
UI Requirements¶
[Required] Clearly collect the Native Pixel ID in a field labeled “Yahoo Pixel ID”.
[Required] Clearly collect the event action, the value you will send in on the ea parameter, in a field labeled “Yahoo Event Action”.
[Required] Clearly collect the
gv
value upon selected event actions chosen: Purchased, AddedtoCart, InitiatedCheckOut.[Optional]: Collect the event category, event label and event value;
Send the event category in on the
ec
parameter, in a field labeled “Yahoo Event Category”;Send the event category in on the
el
parameter, in a field labeled “Yahoo Event Label”;Send the event value in on the
ev
parameter, in a field labeled “Yahoo Event Value”.
Arbitration Result Post-back Spec for 3P Tracking Partners (v1.0)¶
Yahoo Native will begin accepting arbitration result post-back events from verified 3P tracking partners. This enables tracking of partners’ honoring of Yahoo Native SAN conversion claims.
The following are the requirements:
Endpoint¶
POST https://sp.analytics.yahoo.com/spp_ar
The request body should contain the claim response JSON, i.e., the response from the https://sp.analytics.yahoo.com/spp_sa endpoint
Request URL parameters are shown in the table below:
Key |
Description |
Example values |
Type |
Required? |
Allow empty value? |
---|---|---|---|---|---|
dp |
Native 3P provider ID, provided to 3P from a Gemini contact |
For example: kochava |
string |
YES |
No. Must be non-empty and valid. |
ai |
App store ID |
Android: com.yahoo.mobile.client.android.mail iTunes: 577586159 |
string |
YES |
No. Must be non-empty and valid. |
mi |
Google Ad ID, iOS IFA |
|
string |
YES |
No. Must be non-empty and valid. |
ar |
Last touch abitration result |
validated_claim, validated_assist, not_accepted |
string |
YES |
Yes |
arid |
Last touch arbitration GUID |
123456789 |
string |
YES |
Yes |
arc |
Last touch arbitration not accepted reason code |
3 |
string |
NO |
No |
Note
The values should be url-encoded.
Request URL Examples¶
https://sp.analytics.yahoo.com/spp_ar?dp=KCHVA&ai=com.yahoo.mobile.client.android.mail&mi=1234-4567-8790-1234&ar=validate d_claim&arid=123456789
https://sp.analytics.yahoo.com/spp_ar?dp=KCHVA&ai=com.yahoo.mobile.client.android.mail&mi=1234-4567-8790-1234&ar=validate d_assist&arid=123456789
https://sp.analytics.yahoo.com/spp_ar?dp=KCHVA&ai=com.yahoo.mobile.client.android.mail&mi=1234-4567-8790-1234&ar=not_acc epted&arid=123456789&arc=3
Request Body¶
Request body should contain the SAN claim JSON (either app install conversion claim or in-app conversion claim).
Request body examples
{
"original_request": "https://...",
"attribution_guid": 123456789
"claims": [
{
"timestamp_ms": 1445539353000,
"event_type”: 200,
"creative_id": 1923847162,
"creative_name": “creative name",
"adgroup_id": 1324182736,
"adgroup_name": “ad group name",
"campaign_id": 302934875,
"campaign_name": “campaign name",
"advertiser_id": 908733,
"advertiser_name": “advertiser name"
"network_id": "9128376dhfgasd",
"demand_platform_id": 1,
"campaign_type": "App Install"
}, {
"timestamp_ms": 1445539353001,
"event_type”: 200,
"creative_id": 1923847163,
"creative_name": “creative name",
"adgroup_id": 1324182737,
"adgroup_name": “ad group name",
"campaign_id": 302934875,
"campaign_name": “campaign name",
"advertiser_id": 908733,
"advertiser_name": “advertiser name"
"network_id": "9128376dhfgasd",
"demand_platform_id": 1,
"campaign_type": "Reengagement"
}
]
}
Request Headers¶
3P Tracking partners must send the client IP address through X-Forwarded-For
header in the HTTP request.
The general format of the field is:
X-Forwarded-For: client, proxy1, proxy2
Partner Integration for GDPR¶
Requirements to continue running any Yahoo Native ad campaigns.
One of the two following things must be done prior to May 1st, 2018 to continue working with Yahoo Native in any capacity:
All events sent to Yahoo Native must include the IP address. This allows Yahoo Native to determine user jurisdiction and treat data appropriately.
Alternatively, partners can implement the IAB GDPR consent and pass Yahoo Native consent of the user.
Each partner must pass IP address on all installs/in-app events in addition to device ID. This will allow Yahoo Native to determine user jurisdiction when responding to all claims and respond appropriately in cases where Yahoo Native does not have consent per regulations of that user’s jurisdiction. After May 1st, 2018, any partner who has not implemented this will have their integrations shut down globally.
Alternatively, partners can implement the IAB GDPR consent and pass Yahoo Native consent of the user.
Requirements to continue running Yahoo Native EU campaigns
To continue measuring Yahoo Native campaigns in the EU, each partner must complete the following by May 1st, 2018. Partners failing to meet these requirements by May 1st will no longer receive any data from Yahoo Native for EU campaigns until these requirements are met. Yahoo Native will communicate to advertisers which partners have or have not completed this integration in order to set expectations on which campaigns can be ran in the EU.
Each partner must integrate with Yahoo Native’s processor API. This is how Yahoo Native will inform partners of Yahoo Native users invoking their data subject rights granted to them under GDPR.
Each partner must sign a contract to commit to Yahoo Native that they will implement all aspects of GDPR in good faith, including deleting any data received from Yahoo Native when the processor API instructs them to do so.