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.
- 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.
- 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.
- 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.
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.
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:
| 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
Option 2: Forward postbacks directly from your server
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
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 | { "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
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 | { "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
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.
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.
| 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.
Example 1:
In this case, the media partner allows the advertiser to run up to 100 campaigns at the same time. Each campaign is assigned a skad campaign ID (1-100 possible values) in a 1:1 fashion.
SKAdNetwork payload sent to Kochava:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 | { "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.
Example 2:
In this case, the media partner limits the number of campaigns the advertiser can run at the same time. The advertiser is limited to 50 campaigns and max 2 ad groups (sub campaign) per campaign. Each ad group is assigned to a skad campaign ID (1-100 possible values) in a 1:1 fashion. In addition, the partner also wants to pass their own internal ID they assign to each publisher app ID under the site_id field.
SKAdNetwork payload sent to Kochava:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 | { "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.
