SKAdNetwork Partner Certification

Feature Summary: The following document describes the steps necessary to facilitate SKAdNetwork data ingestion to a custom whitelabeled endpoint, as well as updates to your iOS integration templates for the purpose of associating click and impression counts to your SKAdNetwork data. The SKAdNetwork signals will be aggregated and can be made available as summary reports to your Advertising partners via their MMPs. Doing so allows your Advertising partners to retain a holistic view of their marketing efforts.

 

Developing Document: This is a dynamic document that will be updated as Kochava adjusts to changes and updates that come from Apple.


Integration Steps

  1. Choose your subdomain — This will be your unique and secure repository of your SKAdNetwork conversion data.
  2. You will be provided a postback endpoint for sending SKAdNetwork data: {yoursubdomain}.adsmeasurement.com/v1/skad/postback

  3. Provide your SKAdNetwork Ad Network ID to Kochava.
  4. Your Ad Network ID is assigned and provided to you by SKAdNetwork when completing their registration process.

  5. Send SKAdNetwork data to your custom postback endpoint.
  6. NOTE: Regardless of which method you choose to share SKAdNetwork data with Kochava, be sure to send every data point included on the original payload sent to you from SKAdNetwork. Kochava will verify each postback through Apple. If there are any missing data points, the postback will be dropped and not reflected in the Kochava system.

 

Required Data Points:

NameDescription
Type
Req.
versionThe SKAdNetwork API version.String
ad-network-idYour SKAdNetwork Identifier.String
source-identifierKnown as the “campaign ID” in previous SKAdNetwork versions, this value relates to the placement detail of the ad-network served inventory.String***
campaign-idSKAdNetwork Campaign ID.Integer
transaction-idUnique ID for deduplication.String
app-idThe Advertiser app ID in iTunes.Integer
attribution-signatureSKAdNetwork signature as specified by Apple. Used for postback validation.String
redownloadA flag that indicates if the customer reinstalled the app. “true” if this is not the first time the user installed the app, otherwise “false”.Boolean
source-domainIndicating the conversion resulted from a mobile web ad unit.String***
source-app-idThe Publisher app ID in Itunes.Integer**
conversion-valueUnsigned 6-bit value that the installed app provided. The conversion-value appears only if the installed app provides it, and if providing the parameter meets Apple’s privacy threshold. A value between 0-63.Integer**
postback-sequence-indexA total of (3) user activities can be attributed by SKAdNetwork and this value indicates which of the 3 conversion windows that conversion occurred in.Number***
fidelity-typeDifferentiates StoreKit-rendered ads from view-through ads. 1 indicates StoreKit-rendered ads and is supported on iOS 11.3 and later, 0 indicates view-through ads and is supported on iOS 14.5 and later. View-through ads are supported with SKAdNetwork version 2.2 and later.Integer
did-winDifferentiates SKAdNetwork postbacks for the winning ad (did-win=true), vs ads that qualified, but did not win (did-win=false). Postbacks for did-win=false are supported with SKAdNetwork version 3.0+ on devices running iOS 14.6+.Boolean*
coarse-conversion-valueA coarse grained value is a type of hierarchical conversion value and can be low, medium, or high.String***
skad_tsWhen the media partner received the postback from the device, in unix timestamp format.Integer
skad_ipThe header ip of the device where the attribution postback was generated from.String

*Only required on version 3.0+
**Not included on version 3.0+ when did-win=false or when Apple’s privacy thresholds are not met.
***Only required on version 4.0+

 

Option 1: Recommended — Configure an HTTP 307 Redirect

  • For postbacks received from SKAdNetwork, implement a 307 redirect, routing to your custom Kochava-assigned endpoint (see step 1).
  • Append query parameters to the redirect endpoint in order to enrich the original postback with Campaign Name, Campaign ID, etc, as represented in your system. Use the parameter names provided in the table below.

 

Option 2: Forward postbacks directly from your server

  • If you are ingesting the data directly from SKAdNetwork into your internal systems, you can forward those signals to the postback endpoint (provided above, step 1) using the below format. Before forwarding to Kochava, add additional campaign information to the original payload you received from SKAdNetwork.

 

Postback Fields for Option 2:

NameDescription
Type
Req.
partner_campaign_nameThe name of the campaign in the media partner’s platform.String
partner_campaign_idThe ID of the campaign in the media partner’s platform.String
skad_source_identifierThe source ID from SKAdNetwork.String
sub_campaign_nameThe name of the sub-campaign level layer as specified in the media partner’s dashboard. May represent ad group, ad set, line item, etc.String
sub_campaign_idThe ID of the sub-campaign level layer as specified in the media partner’s dashboard. May represent ad group, ad set, line item, etc.String
creative_nameThe name representing the ad creative served.String
creative_idThe numerical id representing the ad creative served.String
site_idThe site ID of the app where the ad was served, shared by the media partner on the ad signal.String
sub_site_idThe sub-site ID of the app where the ad was served, shared by the media partner on the ad signal.String
countryParameter passed by the media partner to Kochava in the payload.String
keywordThe keyword searched by the user that clicked the ad.String
campaign_objectiveObjective of campaign set in media partner dashboard.String
campaign_statusStatus of a campaign in the media partner dashboard.String
exchange_idThe ID of the ad exchange that served the bid request.String
bid_typeBid type set by the media partner.String
bid_strategyThe bid strategy defined by the advertiser in the media partner’s dashboard.String
bid_currencyCurrency of bid amount.String
bid_amountAmount the advertiser bid for the ad to be served.String

 

Postback Ingestion:

HTTPS Post Request —

Header
Content-Type: application/json
Accept: application/json

 

Endpoint
{yoursubdomain}.adsmeasurement.com/v1/skad/postback

  • Body

    {
        "version": "string",
        "ad-network-id": "string",
        "source-identifier": integer,
        "app-id": integer,
        "transaction-id": "string",
        "redownload": boolean,
        "source-domain": "string",
        "fidelity-type": integer,
        "did-win": boolean,
        "conversion-value": unsigned integer,
        "postback-sequence-index": integer,
        "attribution-signature": "string"
    }
    

     

    Example — High Postback Data Tier

    {
      "version": "4.0",
      "ad-network-id": "com.example",
      "source-identifier": "5239",
      "app-id": 525463029,
      "transaction-id": "6aafb7a5-0170-41b5-bbe4-fe71dedf1e30",
      "redownload": false,
      "source-domain": "example.com", 
      "fidelity-type": 1, 
      "did-win": true,
      "conversion-value": 63,
      "postback-sequence-index": 0,
      "attribution-signature": "MEUCIGRmSMrqedNu6uaHyhVcifs118R5z/AB6cvRaKrRRHWRAiEAv96ne3dKQ5kJpbsfk4eYiePmrZUU6sQmo+7zfP/1Bxo="
    }
    

     

    Example — Low Postback Data Tier

    NOTE: The following example the source-identifier contains two digits and the post back includes a coarse-conversion-value

    {
      "version": "4.0",
      "ad-network-id": "com.example",
      "source-identifier": "39",
      "app-id": 525463029,
      "transaction-id": "6aafb7a5-0170-41b5-bbe4-fe71dedf1e31",
      "redownload": false,
      "source-domain": "example.com", 
      "fidelity-type": 1, 
      "did-win": true,
      "coarse-conversion-value": "high",
      "postback-sequence-index": 0,
      "attribution-signature": "MEUCIQD4rX6eh38qEhuUKHdap345UbmlzA7KEZ1bhWZuYM8MJwIgMnyiiZe6heabDkGwOaKBYrUXQhKtF3P/ERHqkR/XpuA="
    }
  • Body

    {
        "version": "string",
        "ad-network-id": "string",
        "campaign-id": integer,
        "transaction-id": "string",
        "app-id": integer,
        "attribution-signature": "string",
        "redownload": boolean,
        "source-app-id": integer,
        "conversion-value": unsigned integer,
        "skad_ip" : "string",
        "skad_ts" : "integer",
        "partner_campaign_name" : "string",
        "partner_campaign_id" : "string"
    }
    

     

    Example

    {
        "version": "2.0",
        "ad-network-id": "1abc12a2a1.skadnetwork",
        "campaign-id": 42,
        "transaction-id": "6aafb7a5-0170-41b5-bbe4-fe71dedf1e28",
        "app-id": 525463029,
        "attribution-signature": "MDYCGQCsQ4y8d4BlYU9b8Qb9BPWPi+ixk/OiRysCGQDZZ8fpJnuqs9my8iSQVbJO/oU1AXUROYU=",
        "redownload": true,
        "source-app-id": 1234567891,
        "conversion-value": 20,
        "skad_ip" : "49.206.2.68",
        "skad_ts" : 1607346100,
        "partner_campaign_name" : "campaign name example",
        "partner_campaign_id" : "123456789"
    }
    

 

 

HTTPS Get Request —

Endpoint
{yoursubdomain}.adsmeasurement.com/v1/skad/postback?version={string}&ad-network-id={string}&campaign-id={integer}&transaction-id={string}&app-id={integer}&attribution-signature={string}&redownload={boolean}&source-app-id={integer}&conversion-value={unsigned integer}&skad_ip={string}&skad_ts={integer}&partner_campaign_name={string}&partner_campaign_id={string}

 

Example
{yoursubdomain}.adsmeasurement.com/v1/skad/postback?version=2.0&ad-network-id=1abc12a2a1.skadnetwork&campaign-id=42&transaction-id=6aafb7a5-0170-41b5-bbe4-fe71dedf1e28&app-id=525463029&attribution-signature=MDYCGQCsQ4y8d4BlYU9b8Qb9BPWPi%2Bixk%2FOiRysCGQDZZ8fpJnuqs9my8iSQVbJO%2FoU1AXUROYU%3D&redownload=false&source-app-id=1234567891&conversion-value=20&skad_ip=49.206.2.68&skad_ts=1607346100&partner_campaign_name=campaign%20name%20example&partner_campaign_id=123456789

 

Confirm the details above with Integrations@kochava.com and we will get to work establishing your domain. As soon as it is complete we will confirm once it is ready to receive data.


Impression/Click Counts and Related Metrics

The following guidance pertains to cases where the media partner is using Option 2 (forwarding SKAdNetwork postback from their own server after enriching with campaign data). Nuances for cases where the media partner is using Option 1 (having SKAdNetwork data sent directly from SKAdNetwork to Kochava) are noted where applicable.

SKAdNetwork reporting in Kochava includes impression/click counts and related metrics. In order to associate this data to SKAdNetwork data, you must pass the same list of campaign enrichment fields on your real-time impressions and clicks as you did on your forwarded SKAdNetwork payloads. In addition, on real-time impression and clicks, you must pass a “skad_mapping” field that is a comma-separated list of campaign enrichment key names. By doing so, Kochava will be able to report on impression/click counts and related metrics to the same level of grouping granularity as your aggregated SKAdNetwork payloads.

 

CAUTION: You must pass the same list of campaign enrichment parameters on your SKAdNetwork payloads as you pass on real-time impressions and clicks, otherwise your impression/click counts will show as zero and related metrics will not be populated.

 

If you are using Option 1 from above (having SKAdNetwork data sent directly from SKAdNetwork to Kochava), you must also pass the SKAdNetwork campaign ID on your real-time impressions and clicks. This allows Kochava to associate campaign data, impression/click counts, and related metrics to your SKAdNetwork data. Mapping for a single skad_campaign_id must be kept consistent for a minimum of 24 hours.

 

KeyDescriptionReq.

skad_mappingComma separated list of key names which match the list of campaign enrichment fields passed on the SKAdNetwork payload.

Example:

skad_mapping=partner_campaign_name,partner_campaign_id,site_id
Yes
skad_campaign_idA number between 1-100.Yes
(if using Option 1)
partner_campaign_nameThe name of the campaign as represented in the partner’s system.Yes
partner_campaign_idThe ID of the campaign as represented in the partner’s system.Yes
sub_campaign_nameNo
sub_campaign_idNo
creative_nameNo
creative_idNo
site_idNo
sub_site_idNo
countryNo
keywordNo
campaign_objectiveNo
campaign_statusNo
exchange_idNo
bid_typeNo
bid_strategyNo
bid_currencyNo
bid_amountNo

 

NOTE: The skad_mapping parameter SHOULD NOT include the actual partner_campaign_name, partner_campaign_id, etc. This needs to be populated with the key name being used to send these values.

 

SKAdNetwork payload sent to Kochava:

{
   "version":"2.0",
   "ad-network-id":"1abc12a2a1.skadnetwork",
   "campaign-id":42,
   "transaction-id":"6aafb7a5-0170-41b5-bbe4-fe71dedf1e28",
   "app-id":525463029,         "attribution-signature":"ABCCGQCsQ4y8d4BlYU9b8Qb9BPWPi+ixk/OiRysCGQDZZ8fpJnuqs9my8iSQVbJO/oU1AXUROYU=",
   "redownload":true,
   "source-app-id":1234567891,
   "conversion-value":20,
   "skad_ip":"49.206.2.68",
   "skad_ts":1607346100,
   "partner_campaign_name":"summer_july_campaign",
   "partner_campaign_id":"13579"
}

 

The campaign enrichment fields, i.e. fields that were not originally sent from SKAdNetwork, but were added to the postback sent to Kochava, in this case are partner_campaign_name and partner_campaign_id.

On the impression/click, the media partner should pass these same fields as well as the skad_mapping field:

  • skad_mapping=partner_campaign_name,partner_campaign_id
  • partner_campaign_name=summer_july_campaign
  • partner_campaign_id=13579

 

Example impression/click —

?skad_mapping=partner_campaign_name,partner_campaign_id&partner_campaign_name=summer_july_campaign&partner_campaign_id=13579&creative_id=banner_1_468x60

NOTE: In this example, creative_id is passed on the impression/click, but is not included in the skad_mapping parameter since it was not included on the SKAdNetwork payload.


 

SKAdNetwork payload sent to Kochava:

{
   "version":"2.0",
   "ad-network-id":"1abc12a2a1.skadnetwork",
   "campaign-id":42,
   "transaction-id":"6aafb7a5-0170-41b5-bbe4-fe71dedf1e28",
   "app-id":525463029,         "attribution-signature":"ABCCGQCsQ4y8d4BlYU9b8Qb9BPWPi+ixk/OiRysCGQDZZ8fpJnuqs9my8iSQVbJO/oU1AXUROYU=",
   "redownload":true,
   "source-app-id":1234567891,
   "conversion-value":20,
   "skad_ip":"49.206.2.68",
 	  "skad_ts":1607346100,
	"partner_campaign_name": "summer_july_campaign",
	"partner_campaign_id": "13579",
            "sub_campaign_name": "summer_independence_day_promo",
            "sub_campaign_id": "2468",
            "site_id": "11223344"     
}

The campaign enrichment fields, i.e. fields that were not originally sent from SKAdNetwork, but were added to the postback sent to Kochava, in this case are partner_campaign_name, partner_campaign_id, sub_campaign_name, sub_campaign_id, and site_id.

On the impression/click, the media partner should pass these same fields as well as the “skad_mapping” field:

  • skad_mapping=partner_campaign_name,partner_campaign_id,sub_campaign_name,sub_campaign_id,site_id
  • partner_campaign_name=summer_july_campaign
  • partner_campaign_id=13579
  • sub_campaign_name=summer_independence_day_promo
  • sub_campaign_id=2468
  • site_id=11223344

 

Example impression/click —

?skad_mapping=partner_campaign_name,partner_campaign_id,sub_campaign_name,sub_campaign_id,site_id&partner_campaign_name=summer_july_campaign&partner_campaign_id=13579&sub_campaign_name=summer_independence_day_promo&sub_campaign_id=2468&site_id=11223344&creative_id=banner_1_468x60

NOTE: In this example, creative_id is passed on the impression/click, but is not included in the skad_mapping parameter since it was not included on the SKAdNetwork payload.


 

Please contact integrations@kochava.com to get your iOS template updated.


SKAdNetwork Reporting

To access aggregated data relating to Kochava advertisers, you can pull from the Kochava reporting API or the Kochava dashboard via your Media Partner account. For more information, please refer to this support documentation.


AdMeasurement (Recommended)

Kochava for Publishers is a SaaS solution for facilitating first-party ad measurement. Kochava for Publishers sits outside and independent of Kochava’s MMP services, and allows for integration with any party granted access as a self-attributing/self-reporting platform with configurable lookback windows and attribution rules, including cross-device & cross-platform attribution.

If you are interested in utilizing Kochava for Publishers for first-party ad measurement in conjunction with SKAdNetwork support, please contact us to learn more.

 
 

Last Modified: Nov 16, 2023 at 3:36 pm