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.
Integration Steps
- Choose your subdomain — This will be your unique and secure repository of your SKAdNetwork conversion data.
- Provide your SKAdNetwork Ad Network ID to Kochava.
- Send SKAdNetwork data to your custom postback endpoint.
- 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.
You will be provided a postback endpoint for sending SKAdNetwork data: {yoursubdomain}.adsmeasurement.com/v1/skad/postback
Your Ad Network ID is assigned and provided to you by SKAdNetwork when completing their registration process.
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. | String |
Postback Ingestion:
HTTPS Post Request —
Header
Content-Type: application/json
Accept: application/json
Endpoint
{yoursubdomain}.adsmeasurement.com/v1/skad/postback
Body
1 2 3 4 5 6 7 8 9 10 11 12 13 |
{ "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" : "string" } |
Example
1 2 3 4 5 6 7 8 9 10 11 12 13 |
{ "version": "2.0", "ad-network-id": "com.example", "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" } |
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={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+ixk/OiRysCGQDZZ8fpJnuqs9my8iSQVbJO/oU1AXUROYU=&redownload=false&source-app-id=1234567891&conversion-value=20&skad_ip=49.206.2.68&skad_ts=1607346100
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, geo and creative in the example below). Parameters that are not used for SKAdNetwork Campaign ID mapping can be sent on the URL, but should not be included within the skad_mapping parameter (keyword in the example below). Keyword in this example is not unique to the skad_campaign_id and should not be listed in skad_mapping.
Example Click 1:
1 |
?skad_campaign_id=1&skad_mapping=partner_campaign_name,geo,creative&partner_campaign_name=A&geo=B&creative=C&keyword=E |
Example Click 2:
1 |
?skad_campaign_id=1&skad_mapping=partner_campaign_name,geo,creative&partner_campaign_name=A&geo=B&creative=C&keyword=F |
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.