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

  2. Provide your SKAdNetwork Ad Network ID to Free App Analytics.

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

  3. Send SKAdNetwork data to your custom postback endpoint.

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

     

    Required Data Points:

    Name Description
    Type
    Req.
    version The SKAdNetwork API version. String ✔
    ad-network-id Your SKAdNetwork Identifier. String ✔
    campaign-id SKAdNetwork Campaign ID. Integer ✔
    transaction-id Unique ID for deduplication. String ✔
    app-id The Advertiser app ID in iTunes. Integer ✔
    attribution-signature SKAdNetwork signature as specified by Apple. Used for postback validation. String ✔
    redownload A 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-app-id The Publisher app ID in Itunes. Integer ✔***
    conversion-value Unsigned 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 ✔***
    fidelity-type Differentiates 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-win Differentiates 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 ✔**
    skad_ts When the media partner received the postback from the device, in unix timestamp format. Integer ✔
    skad_ip The header ip of the device where the attribution postback was generated from. String ✔

    *Only required on version 2.2+.
    **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.

     

    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 Free App Analytics, add additional campaign information to the original payload you received from SKAdNetwork.

     

    Postback Fields for Option 2:

    Name Description
    Type
    Req.
    partner_campaign_name The name of the campaign in the media partner’s platform. String ✔
    partner_campaign_id The ID of the campaign in the media partner’s platform. String ✔
    sub_campaign_name String
    sub_campaign_id String
    creative_name String
    creative_id String
    site_id String
    sub_site_id String
    country String
    keyword String
    campaign_objective String
    campaign_status String
    exchange_id String
    bid_type String
    bid_strategy String
    bid_currency String
    bid_amount String

     

    Postback Ingestion:

    HTTPS Post Request —

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

     

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

     

    Body

     

    Example

     

    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

     

  4. 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 Free App Analytics) are noted where applicable.

SKAdNetwork reporting in Free App Analytics 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, Free App Analytics 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 Free App Analytics), you must also pass the SKAdNetwork campaign ID on your real-time impressions and clicks. This allows Free App Analytics 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.

 

Key Description Req.
skad_mapping Comma separated list of key names which match the list of campaign enrichment fields passed on the SKAdNetwork payload.

Example:

 Yes
skad_campaign_id A number between 1-100. Yes
(if using Option 1)
partner_campaign_name The name of the campaign as represented in the partner’s system. Yes
partner_campaign_id The ID of the campaign as represented in the partner’s system. Yes
sub_campaign_name No
sub_campaign_id No
creative_name No
creative_id No
site_id No
sub_site_id No
country No
keyword No
campaign_objective No
campaign_status No
exchange_id No
bid_type No
bid_strategy No
bid_currency No
bid_amount No

 

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 Free App Analytics:

 

The campaign enrichment fields, i.e. fields that were not originally sent from SKAdNetwork, but were added to the postback sent to Free App Analytics, 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 Free App Analytics:

The campaign enrichment fields, i.e. fields that were not originally sent from SKAdNetwork, but were added to the postback sent to Free App Analytics, 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 Free App Analytics advertisers, you can pull from the Kochava reporting API or the Free App Analytics 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: Dec 6, 2022 at 10:27 am