Server-to-Server In-app Events Specification v1.0

This specification describes the new Server-to-Server In-App events integration with Native & Search. The spec is intended for 3rd Party Mobile Measurement Providers (3PMMP) who wish to integrate with Native & Search via S2S, and is aimed at Data Providers like Kochava, Tune, AppsFlyer, Adjust, Apsalar, CyberZ/FOX and others.

Native & Search 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
a static hard-coded value Static value. Must be 8 int Yes No. Must be non-empty & valid.
.yp Native & Search advertiser pixel ID, provided to 3rd parties from the advertiser. 123456 int Yes No. Must be non-empty & valid.
dp Native & Search 3P provider ID, provided to 3rd Parties from Native & Search contact. e.g., kochava string Yes No. Must be non-empty & valid.
ai App store ID

Android:

com.yahoo.mobile.client.android.mail. iTunes: 577586159

string Yes No. Must be non-empty & valid.
mi 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
js no Static value. Should always be no string Yes No. Must be non-empty & valid.
ec Category of the event type
  • Purchase
  • Sign Up
  • Lead
  • Add To Cart
  • View Content
  • Add To Wishlist
  • Initiate Checkout
  • Add Payment Info
  • Others
string Yes Yes. The value can be empty per advertiser choice.
Key Description Values Type Code required Allow empty value
ea Name of specific event

Valid values are:

  • AchievedLevel
  • ActivatedApp
  • AddedPaymentInfo
  • AddedToCart
  • AddedToWishlist
  • CompletedRegistration
  • CompletedTutorial
  • InitiatedCheckout
  • Purchased
  • Rated
  • Searched
  • Lead
  • SignUp
  • SpentCredits
  • UnlockedAchievement
  • ViewedContent
  • [CUSTOM VALUE]
string Yes No. Must be non-empty & valid.
Key Description Values Type Code required Allow empty value
el Additional event label [CUSTOM VALUE] string Yes Yes. The value can be empty per advertiser choice.
ev Numeric data associated with the event [CUSTOM VALUE] Fixed point Yes Yes. The value can be empty per advertiser choice.
gv 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
gc Country currency USD string Yes No.
id Self-attribution request id 1234172534 string Yes No.
et In-app event time, in milliseconds 1453497859 int Yes No.
ua User Agent Info

Key-value pairs of user agent identifying information. Format:

  • a url-encoded list of key-value pairs with the following delimiters: ‘;’
  • delimeter between key-value pair ‘=’
  • delimiter between a key and a value. Example:

&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 ua can be omitted if the 3P tracking partner does not have the information for the keys. Yes. Some keys that make up ua can be omitted if the 3P tracking partner does not have the information for keys.
Key Description Values Type Code required Allow empty value
ir Google referrer id

Google install referrer value, without filtering.

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

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.
ip client IP address 1.2.3.4 string Yes No
ipv6 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:

http://sp.analytics.yahoo.com/spp_sa
http://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
an App package name com.yahoo.frontpage com.appdeveloper.name
av App version 5.3 4.75
on OS name iOS Android
ov OS version 10.2 7.0
ob OS build   NBD92B
dm Device manufacturer Apple Motorola
do Device model  

Nexus 6

Data source: android.os.Build.MODEL

dn 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

sz Device screen size (inches) 4.7 5.66
sd 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 availability.

{
     "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"
                                  },
                                  "ip_address": {
                                          "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 availability.

{
     "original_request": "http://...",
          "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",
                  "ip_address": "10.20.30.40",
                  "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",
                  "ip_address": "10.20.30.41",
                  "demand_platform_id": 2,
                  "campaign_type": "Reengagement"
             }
           ],
         "network_id": "9128376dhfgasd"
}

Response field types and descriptions are shown in the table below.

Field Type Description
original.request string Original app install request from 3P Data Provider.
claims.timestamp_ms integer Event timestamp, in milliseconds.
claims.event_type integer

Event type:

100 = impression 200 = click 300 = app install

claims.creative_id integer Native & Search creative (ad) id.
claims.creative_name string Native & Search creative (ad) name.
claims.adgroup_id integer Native & Search ad group id.
claims.adgroup_name string Native & Search ad group name.
claims.campaign_id integer Native & Search campaign id.
claims.campaign_name string Native & Search campaign name.
claims.advertiser_id integer Native & Search advertiser id.
claims.advertiser_name string Native & Search advertiser name.
claims.ip_address string client IP address.
claims.match_type string Attribution claim method: identifier, fingerprint, referrer. Note: This is an optional field (may or may not be returned).
claims.demand_platform_id integer Id to allow measurement partner to determine which Oath demand platform served the claim. Note that 1 is for Native & Search, 2 is for BrightRoll DSP.
claims.campaign_type string Used to share different campaign objectives to 3P. Note that this is for App Install, Reengagement campaigns.
network_id string Id to identify Native & Search 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

  1. [Required] Clearly collect the Native & Search Pixel ID in a field labeled “Yahoo Pixel ID”.
  2. [Required] Clearly collect the event action, the value you will send in on the ea parameter, in a field labeled “Yahoo Event Action”.
  3. [Required] Clearly collect the gv value upon selected event actions chosen: Purchased, AddedtoCart, InitiatedCheckOut.
  4. [Optional]: Collect the event category, event label and event value;
    1. Send the event category in on the ec parameter, in a field labeled “Yahoo Event Category”;
    2. Send the event category in on the el parameter, in a field labeled “Yahoo Event Label”;
    3. Send the event value in on the ev parameter, in a field labeled “Yahoo Event Value”.

Partner Integration for GDPR

Requirements to continue running any Oath ad campaigns.

One of the two following things must be done prior to May 1st, 2018 to continue working with Oath in any capacity:

  • All events sent to Oath must include IP address. This will allow Oath to determine user jurisdiction and treat data appropriately.
  • Alternatively, partners can implement the IAB GDPR consent and pass Oath consent of the user.

Each partner must pass IP address on all installs/in-app events in addition to device ID.  This will allow Oath to determine user jurisdiction when responding to all claims and respond appropriately in cases where Oath 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 Oath consent of the user.

Requirements to continue running Oath EU campaigns

To continue measuring Oath 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 Oath for EU campaigns until these requirements are met. Oath 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 Oath’s processor API. This is how Oath will inform partners of Oath users invoking their data subject rights granted to them under GDPR.
  • Each partner must sign a contract to commit to Oath that they will implement all aspects of GDPR in good faith, including deleting any data received from Oath when the processor API instructs them to do so.