Server-to-Server App Install Specification v2.0

This specification describes the new Server-to-Server app install integration with Yahoo Gemini. The spec is intended for 3rd Party Mobile Measurement Providers (3PMMP) who wish to integrate with Yahoo Gemini 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 Gemini 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.

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 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 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 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 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 tries to attribute the install.
  5. If Yahoo 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

Parameter For First URL

Note that the bs parameter must be passed as the first URL. This string parameter 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>.

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

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

Fields for Endpoint

The following fields are for this endpoint:

<endpoint_cname> = notify.beap.gemini.yahoo.com
Field 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 Yahoo Gemini.
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

Fields

The following tables list the fields required to work with server-to-server app install integrations.

Key spp.pl or spp_endpoint Description Values Type Code required Allow empty value
a both static hard-coded value Static value. Must be 8 int Yes No. Must be non-empty & valid.
.yp both Gemini advertiser pixel ID, provided to 3rd parties from the advertiser. 123456 int Yes No. Must be non-empty & valid.
dp both Gemini 3P provider ID, provided to 3rd Parties from Gemini contact. e.g., kochava string Yes No. Must be non-empty & valid.
ai both App store ID

Android:

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

string Yes No. Must be non-empty & valid.
mi both 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 spp.pl or spp_endpoint Description Values Type Code required Allow empty value
js both no Static value. Should always be no string Yes No. Must be non-empty & valid.
ec both Category of the event type
  • Gaming
  • Engagement
  • Lead
  • Purchase
  • Add to cart
  • Sign up
string Yes Yes. The value can be empty per advertiser choice.
Key spp.pl or spp_endpoint Description Values Type Code required Allow empty value
ea both Name of specific event

Valid values are:

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

http://sp.analytics.yahoo.com/spp_sa.pl?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 Format

(/ssa_sa.pl self-attribution endpoint only)

Response JSON Schema

Note

claims.network_id is an optional string field that identifies the Yahoo Gemini ID to 3P Data Providers, and is included for purposes of completion in the schema shown below.

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

Response JSON Example

Note

claims.network_id is an optional string field that identifies the Yahoo Gemini ID to 3P Data Providers, and is included for purposes of completion in the example shown below.

{
     "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",
             "network_id": "9128376dhfgasd"
        },
          {
             "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",
             "network_id": "9128376dhfgasd"
        }
      ]
}

Response field types and description 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
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 Yahoo Gemini creative (ad) id.
claims.creative_name string Yahoo Gemini creative (ad) name.
claims.adgroup_id integer Yahoo Gemini ad group id.
claims.adgroup_name string Yahoo Gemini ad group name.
claims.campaign_id integer Yahoo Gemini campaign id.
claims.campaign_name string Yahoo Gemini campaign name.
claims.advertiser_id integer Yahoo Gemini advertiser id.
claims.advertiser_name string Yahoo Gemini advertiser name.
claims.ip_address string client IP address.
claims.network_id string Id to identify Yahoo Gemini to 3P Data Providers. Note that is an optional field.
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 Gemini, 2 is for BrightRoll DSP.
claims.campaign_type string Used to share different campaign objectives to 3P. Note that this is for INSTALL_APP, REENGAGE_APP, Null.

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 Yahoo 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; a. Send the event category in on the ec parameter, in a field labeled “Yahoo Event Category”; b. Send the event category in on the el parameter, in a field labeled “Yahoo Event Label”; c. Send the event value in on the ev parameter, in a field labeled “Yahoo Event Value”.