SKAdNetwork Partner Certification


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 campaign data mapping. 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 Kochava.

    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. Option 1: Recommended — Have SKAdNetwork data sent directly from SKAdNetwork. Use the provided postback URL as the conversion postback destination when registering with SKAdNetwork. The attribution signature will be used to validate the postback with Apple and the transaction-id will be used for deduplication.

    NOTE: Upon registering with SKAdNetwork, you will receive an email from Apple requesting a URL to send conversion postbacks to. This is the URL you should supply.

    Option 2: If you are ingesting the data directly from SKAd into your internal systems, you can forward those signals to the postback endpoint (provided above, step 1) using the below format. The attribution signature will be used to validate the postback with Apple and the transaction-id will be used for deduplication.

     

    Required Fields for Option 2:

    Name Description Type
    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/false
    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. Unsigned Integer
    skad_ip The header ip of the device where the attribution postback was generated from. String
    skad_ts When the media partner received the postback from the device, in unix timestamp format. Integer
    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

     

    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=com.example&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’ll get to work establishing your domain. As soon as it’s complete we’ll confirm once it’s ready to receive data.

SKAdNetwork Reporting API

A separate, reporting-focused spec will be provided pending potential changes introduced by Apple during the beta. The document will outline how to make SKAdNetwork data available to MMPs, who can in turn make it available to advertisers.

SKAdNetwork Data Mapping

Mapping for a single skad_campaign_id must be kept consistent for a minimum of 24 hours.
Please see the below table for required updates to your iOS integration:

 

Key Value Required/Optional
skad_campaign_id A number between 1-100. Required
partner_campaign_name The name of the campaign as represented in the partner’s system. Required
skad_mapping A list of campaign-related parameters that have unique values associated to the skad_campaign_id. Any parameters listed under skad_mapping must be have 1:1 values with the skad_campaign_id.

Example: partner_campaign_name 		Required

 

Optional Reporting Granularity:

The above required fields allow for reporting SKAdNetwork data by partner_campaign_name. If additional campaign metadata is being incorporated into the skadnetwork campaign ID mapping, those parameters (see supported list below), as well as a skad_mapping parameter should be added to your template.

 

Supported skad_mapping Parameters:

  • bid_amount
  • bid_currency
  • bid_strategy
  • bid_type
  • campaign_objective
  • campaign_status
  • country
  • creative_id
  • creative_name
  • exchange_id
  • keyword
  • partner_campaign_id
  • partner_campaign_name
  • site_id
  • sub_campaign_id
  • sub_campaign_name
  • sub_site_id

The skad_mapping field is a list of parameters that are incorporated into the SKAdNetwork Campaign ID mapping (partner_campaign_name, country, and creative_id in the example below). This field should only include the keys for the parameters being sent on the click that are unique to the the skad_campaign_id. Parameters that are not used for SKAdNetwork Campaign ID mapping can be sent on the click, but SHOULD NOT be included within the skad_mapping field (keyword in the example below).

Keyword in this example is not unique to the skad_campaign_id and should not be included in the skad_mapping value.

For example, if skad_campaign_id=1 maps to partner_campaign_name=campaign_1, country=US, and creative_id=banner_1_468x60, but the keyword can be different on each click that has the same skad_campaign_id, here is how the clicks should be received:

 

Example Click 1:

 

Example Click 2:

NOTE: The skad_mapping parameter SHOULD NOT include the actual partner_campaign_name, country, or creative_id values. This needs to be populated with the keys being used to send these values (see list of supported skad_mapping parameters above).

 

Passing these parameters, as well as the skad_mapping field will allow advertisers to view SKAdNetwork data with additional granularity, beyond partner_campaign_name. This step is optional and should be used when you are limiting the number of campaigns that can be concurrently running to less than 100 for the purpose of incorporating additional campaign metadata into your SKAdNetwork campaign ID definitions.

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

AdsMeasurment(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.