Server-to-Server App Install Specification v2.1

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

The goal of this effort is to eliminate the use of client-side tracking URLs for app install conversions, and provide faster, more reliable conversion tracking for Yahoo Native 3rd Party Data Providers.

Third-party Data Providers are encouraged to take advantage of this spec and use it to code up for improved app install and in-app event integration.

For information about in-app event integration, refer to the Server-to-Server In-app Events Specification v1.0.

Important

Support is only provided for one SDK attribution partner per app at this time.

Implementation

Once 3rd Party Data Providers are familiar with the spec, Yahoo Native will do the following:

  1. Generate an authentication key, provided in a password protected zip file. The password will be provided verbally from your Yahoo Native contact.

  2. As a Data Provider, you will implement this request:

https://<endpoint_cname>/appinstall?bs=<sig>&dp=<data_provider_id>&id=<request_guid>&ai=<app_store_id>&mi=<idfa>&it=<app_first_time_launch_time>&ir=<install_referrer>&ua=<user_agent>&ip=<ip_address>&ipv6<ipv6_address>

<endpoint_cname> = notify.beap.gemini.yahoo.com

Test Phase 1

Follow these steps:

  1. Yahoo Native will provide you with mobile ids for iOS and Android, which you can use for testing during Phase 1.

  2. As a Data Provider, you will send a call to the production endpoint with the those ids.

  3. Yahoo Native will verify the request.

  4. You should then validate the response.

Test Phase 2

Follow these steps:

  1. Switch traffic on production for 1 hour.

  2. Confirm that you will not be sending the post-backs to the legacy endpoint during the 1-hr test. This will prevent duplicate conversions.


Note

Migration (optional). For Data providers who are currently using the click method, a migration process will be discussed. If possible, a hard cut-off time is preferred for simplicity.

Typical Workflow

This is the workflow sequence that occurs when the user who clicks on an ad, the Data Provider receives a call and Yahoo tries to attribute the app install:

  1. A user clicks an ad, downloads an app, and opens the app.

  2. The Data Provider receives a call from the app with specific details.

  3. The Data Provider populates the JSON request below with the required details. Note that all installations will need to be sent.

  4. Yahoo Native tries to attribute the install.

  5. If Yahoo Native can match the installation, the response will contain the claim attribute with the appropriate information.

  6. If not, the request will be returned without a claims attribute.

Request

Make this request:

https://<endpoint_cname>/appinstall?bs=<sig>&dp=<data_provider_id>&id=<request_guid>&ai=<app_store_id>&mi=<idfa>&it=<app_first_time_launch_time>&ir=<install_referrer>&ua=<user_agent>&ip=<ip_address>&ipv6<ipv6_address>

Specify this as your endpoint:

<endpoint_cname> = notify.beap.gemini.yahoo.com

Signature Calculation

Note that the bs parameter must be passed as the first query parameter. This string parameter is an HMAC SHA-256 in HEX format signature of the request string, starting from /appinstall? until the end of string, excluding bs-<sig>.

For example:

/appinstall?dp=<data_provider_id>&id=<request_guid>&ai=<app_store_id>&mi=<idfa>&it=<app_first_time_launch_time>&ir=<install_referrer>&ua=<user_agent_info>&ip=<ip_address>&ipv6_address>

Use the authentication key provided to you in order to generate the signature.

Signature Calculation Example

Request URL:

https://notify.beap.gemini.yahoo.com/appinstall?bs=67d171ba95e8e3128f55fddfd9d972657a76565a6fab0b88156176b6aa1022f3&dp=kochava&id=02a99ce530a749d5a2-20180216-194192%3Abcf7e144f1bbf068d1-20180216-194192&mi=ABCDE-B076-4E88-96A5-73840735639D&ai=401386351&it=1518760241642&ir=&ua=an%3Dcom.yahoo.frontpage%3Bav%3D5.3%3Bon%3DiOS%3Bov%3D10.2%3Bdm%3DApple%3Bdo%3DiPhone7%3Bsz%3D4.7%3Bsd%3D1224x750&ip=64.18.3.122

String to be signed:

/appinstall?dp=kochava&id=02a99ce530a749d5a2-20180216-194192%3Abcf7e144f1bbf068d1-20180216-194192&mi=ABCDE-B076-4E88-96A5-73840735639D&ai=401386351&it=1518760241642&ir=&ua=an%3Dcom.yahoo.frontpage%3Bav%3D5.3%3Bon%3DiOS%3Bov%3D10.2%3Bdm%3DApple%3Bdo%3DiPhone7%3Bsz%3D4.7%3Bsd%3D1224x750&ip=64.18.3.122

Sample authentication key: abcde1234

The calculated signature from the example:

67d171ba95e8e3128f55fddfd9d972657a76565a6fab0b88156176b6aa1022f3

Fields for Install Events Endpoint

The following fields are for this endpoint:

<endpoint_cname> = notify.beap.gemini.yahoo.com

Fields

Type

Description

bs

string

This is an HMAC SHA-256 in HEX format signature of the request string, starting from /appinstall? until the end of the string, excluding bs=<sig>.

dp

string

Id of the 3P data providers for identification to Native & Search.

id

string

Request’s globally unique identifier (GUID), for debugging/troubleshooting.

ai

string

App store id: 9-digit numeric id for iTunes, package name for Android.

mi

string

IDFA / advertising id.

it

integer

App first time launch time, in milliseconds.

ir

string

Google install referrer value, without filtering.

For example:

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

ua

string

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%3Bdm%3DApple%3Bdo%3DiPhone7%3Bsz%3D4.7%3Bsd%3D1224x750

See details on the supported keys in the table below.

ip

string

1.2.3.4

ipv6

string

2001%3Adb8%3A85a3%3A8d3%3A1319%3A8a2e%3A370%3A7348

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.

{
        "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"
                                },
                                "site_id": {
                                        "type": "string"
                                }
                        }
                }
       },
        "network_id": {
                    "type": "string"
        }
}

Response JSON Example

{
     "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",
             "site_id": "dhjs8723tgajshd23a",

       }],
  "network_id": "9128376dhfgasd"
}

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

Note

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.

Field

Type

Description

Comments

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

claims.creative_id

integer

Native creative (ad) id.

claims.creative_name

string

Native creative (ad) name.

claims.adgroup_id

integer

Native ad group id.

claims.adgroup_name

string

Native ad group name.

claims.campaign_id

integer

Native campaign id.

claims.campaign_name

string

Native campaign name.

claims.advertiser_id

integer

Native advertiser id.

claims.advertiser_name

string

Native advertiser name.

claims.demand_platform_id

integer

Id to allow measurement partner to determine which Yahoo Native demand platform served the claim.

Note that 1 is for Native Ad Platform, 2 is for the DSP.

claims.campaign_type

string

Used to share different campaign objectives to 3P.

Note that this is for App Install or Reengagement campaigns.

network_id

string

Id to identify Native Ad Platform to 3P Data Providers.

Note that is an optional field.

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 http://sp.analytics.yahoo.com/spp_ar

Request URL parameters are shown in the table below:

Key

Description

Example values

Type

Required?

Allow empty value?

dp

Native & Search 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
Accepted ad IDs are:
  • iOS IFA: 67247000-921f-41a1-ab22-b98b50716 40f

    • Google Ad Id: 38400000-8cf0-11bd-b23e-10b96e400 00d

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

http://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
http://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
http://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": "http://...",
   "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 IP address. This will allow 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.