SKAdNetwork Integration Guide - Airbridge Help Center

This guide is intended to share how Airbridge and its partnered ad networks can be integrated with iOS’s new SKAdNetwork system. The integration enables Airbridge to receive attribution results from publishers, and Ad Networks can get the advertiser’s decoded conversion values configured in Airbridge by using the SKAN conversion value configuration API.

SkAdNetwork Workflow

SKAdNetwork attribution data must go through the following three steps to be properly processed and delivered to the advertiser as final aggregated results.

iOS Device → Ad Network Postback (Developed by the Advertiser)
Ad Network → Airbridge
Airbridge → Ad Network Postback

Ad Network → Airbridge Postback

The ad network should forward SKAdNetwork postbacks to Airbridge using the Airbridge SKAN Postback API. From the below table, parameters with “SKAdNetwork Postback” as their source should be sent as-is. The parameters with “Ad Network” as their source are parameters that the ad network derives from the SKAdNetwork postback information and sends to Airbridge for a more in-depth analysis.

Parameter	Required	Description	Source	Type
version	true	SkAdNetwork Documentation (* For version < 2.0, set `NULL`)	SkAdNetwork Postback	string (nullable)
ad-network-id	true	SkAdNetwork Documentation	SkAdNetwork Postback	string
campaign-id	true (* For version 3.0 and before)	SkAdNetwork Documentation	SkAdNetwork Postback	integer
source-identifier	true (* For version 4.0 and later)	SkAdNetwork Documentation(* For version < 4.0, set `NULL`)	SkAdNetwork Postback	string
transaction-id	true	SkAdNetwork Documentation	SkAdNetwork Postback	string
app-id	true	SkAdNetwork Documentation	SkAdNetwork Postback	integer
attribution-signature	true	SkAdNetwork Documentation	SkAdNetwork Postback	string
redownload	true (* For version 2.0 and later)	SkAdNetwork Documentation(* For version < 2.0, set `NULL`)	SkAdNetwork Postback	boolean
fidelity-type	true (* For version 2.2 and later)	SkAdNetwork Documentation - For version < 2.2, set `NULL`)	SkAdNetwork Postback	integer
did-win	true (* For version 3.0 and later)	SkAdNetwork Documentation - For version < 3.0, set `NULL`)	SkAdNetwork Postback	boolean
postback-sequence-index	true (* For version 4.0 and later)	SkAdNetwork Documentation - For version < 4.0, set `NULL`)	SkAdNetwork Postback	integer
source-app-id	false	SkAdNetwork Documentation	SkAdNetwork Postback	integer
conversion-value	true	SkAdNetwork Documentation	SkAdNetwork Postback	integer
coarse-conversion-value	true (* For version 4.0 and later)	SkAdNetwork Documentation	SkAdNetwork Postback	string
attributed-channel	true	Attributed Channel (Registered Name on Airbridge)	Ad Network	string
attributed-campaign	true	Attributed Campaign	Ad Network	string
attributed-campaign-id	true	Attributed Campaign ID	Ad Network	string
attributed-ad-group	false	Attributed Ad Group	Ad Network	string
attributed-ad-group-id	false	Attributed Ad Group ID	Ad Network	string
attributed-ad-creative	false	Attributed Ad Creative	Ad Network	string
attributed-ad-creative-id	false	Attributed Ad Creative ID	Ad Network	string
attributed-sub-publisher	false	Attributed Sub Publisher	Ad Network	string
attributed-sub-sub-publisher-1	false	Attributed Sub Sub Publisher 1	Ad Network	string
attributed-sub-sub-publisher-2	false	Attributed Sub Sub Publisher 2	Ad Network	string
attributed-sub-sub-publisher-3	false	Attributed Sub Sub Publisher 3	Ad Network	string
ip	false	Device Public IP	Ad Network	string
timestamp	true	Timestamp of when the postback is received by the ad network from the iOS device. Provided as a 13-digit UNIX timestamp.	Ad Network	integer

Option 1. POST Method

The Ad Network receives SKAdNetwork postbacks from a device and then forwards it to Airbridge using the POST method.

HTTP Protocol

Method	POST
Endpoint	`https://postback.airbridge.io/skadnetwork/v1`
Content-Type	application/json
Response	200: OK 400: Validation Error

When forwarding postbacks to Airbridge, the following information needs to be included in the POST Body. (See below table for details) Mandatory:

All information included in the SKAdNetwork Postback
Attributed channel name (attributed-channel)
Attributed campaign name (attributed-campaign) and campaign ID (attributed-campaign-id)
The timestamp of the postback sent from the iOS device

Optional:

Campaign parameters other than the campaign name (attributed-campaign) and campaign ID (attributed-campaign-id)

Example

cURL

curl --location --request POST 'https://postback.airbridge.io/skadnetwork/v1' \
--header 'Content-type: application/json' \
--data-raw '{
    "version":"2.0",
    "ad-network-id": "abcabcabc.skadnetwork",
    "campaign-id": 99,
    "transaction-id": "68eb3d91-15f5-44ee-9267-25c7655c20b6",
    "app-id": 888707086,
    "attribution-signature": "MDYCGQCsQ4y8d4BlYU9b8Qb9BPWPi+ixk/OiRysCGQDZZ8fpJnuqs9my8iSQVbJO/oU1AXUROYU=",
    "redownload": false,
    "source-app-id": 888707074,
    "conversion-value": 63,
    "attributed-channel": "adnetwork_abc",
    "attributed-campaign": "test_campaign",
    "attributed-campaign-id": "test_campaign_id",
    "ip": "192.0.2.0",
    "timestamp": 1607678183995
}'

Option 2. 307 Redirect

The Ad Network receives SKAdNetwork postbacks from a device and then responds with a 307 redirect. This will request the device to send SKAdNetwork postbacks to Airbridge directly.

HTTP Protocol

Method	307 Redirect
Endpoint	`https://postback.airbridge.io/skadnetwork/v1`
Response	200: OK 400: Validation Error

When configuring the redirect URL, the following information needs to be appended to GET Parameters. (See below table for details) Mandatory:

Attributed channel name (attributed-channel)

Optional:

Campaign parameters

Parameter	Required	Description	Source
attributed-channel	true	Attributed Channel (Registered Name on Airbridge)	Ad Network
attributed-campaign	true	Attributed Campaign	Ad Network
attributed-campaign-id	true	Attributed Campaign ID	Ad Network
attributed-ad-group	false	Attributed Ad Group	Ad Network
attributed-ad-group-id	false	Attributed Ad Group ID	Ad Network
attributed-ad-creative	false	Attributed Ad Creative	Ad Network
attributed-ad-creative-id	false	Attributed Ad Creative ID	Ad Network
attributed-sub-publisher	false	Attributed Sub Publisher	Ad Network
attributed-sub-sub-publisher-1	false	Attributed Sub Sub Publisher 1	Ad Network
attributed-sub-sub-publisher-2	false	Attributed Sub Sub Publisher 2	Ad Network
attributed-sub-sub-publisher-3	false	Attributed Sub Sub Publisher 3	Ad Network

Example

https://postback.airbridge.io/skadnetwork/v1?attributed-channel=adnetwork_abc&attributed-campaign=test_campaign&attributed-campaign-id=test_campaign_id

Checklist for Ad NetworksTransmit the payload containing the required parameters and parameters related to the ad campaign that received the attribution credit to the Airbridge postback server (postback.airbridge.io). Upon successful transmission, a 200 response is expected.

Airbridge → Ad Network

Option 1. SKAdNetwork Conversion Value Config API

SKAdNetwork Conversion Value Config API provides Ad Networks with the advertiser’s conversion value configuration. The ad network will use this information to decode conversion values directly. Query Parameters:

api_key
itunes_app_id (digits only, without the “id” prefix)
response_format

Checklist for Ad Networkapi_key and response_format are unique values per Ad Network. Please contact the Airbridge Platform team to receive yours.

Request Example

https://api.airbridge.io/skadnetwork/conversion-bit-config/v2?api_key={YOUR_API_KEY}&response_format={YOUR_RESPONE_FORMAT}&itunes_app_id={CLIENT_APP_ID}

Response Example

Field	Description	Always include?
default_currency	Default currency	True
last_update_time	Last updated datetime (epoch/unix timestamp in seconds)	True
conversion_bits_rules	List of conversion value rules	True
conversion_bits_rules.$.conversion_value	Conversion value of this rule	True
conversion_bits_rules.$.events	List of the corresponding events of the rule	True
conversion_bits_rules. $.events.$ .event_name	Event name	True
conversion_bits_rules. $.events.$ .values	The object containing event value range for the event	False (when value set ranges are used)
conversion_bits_rules. $.events.$ .values.amount	The starting amount of the value range (equal to or greater than)	False (when value set ranges are used)
conversion_bits_rules. $.events.$ .values.max_amount	The max amount of the value range (less than)	False (when value set ranges are used)

{
  "default_currency": "KRW",
  "last_update_time": 1642145867,
  "conversion_bits_rules": [
    {
      "conversion_value": 0,
      "events": []
    },
    {
      "conversion_value": 1,
      "events": [
        {
          "event_name": "airbridge.ecommerce.order.completed"
        }
      ]
    },
    {
      "conversion_value": 2,
      "events": [
        {
          "event_name": "airbridge.ecommerce.order.completed"
        }
      ]
    },
    ...
    {
      "conversion_value": 63,
      "events": [
        {
          "event_name": "airbridge.ecommerce.order.completed",
          "values": {
            "amount": 14000
          }
        }
      ]
    }
  ]
}

For more details, please visit our API reference page.

Option 2. Decoded SKAdNetwork Postback

Airbridge decodes the conversion values transferred by the ad network, processes it into finalized attribution information, and sends the postback back to the ad network. If you wish to proceed with this option, please contact the Airbridge CSM.

​SkAdNetwork Workflow

​Ad Network → Airbridge Postback

​Option 1. POST Method

​HTTP Protocol

Example

​Option 2. 307 Redirect

​HTTP Protocol

Example

​Airbridge → Ad Network

​Option 1. SKAdNetwork Conversion Value Config API

Request Example

Response Example

​Option 2. Decoded SKAdNetwork Postback

SkAdNetwork Workflow

Ad Network → Airbridge Postback

Option 1. POST Method

HTTP Protocol

Option 2. 307 Redirect

HTTP Protocol

Airbridge → Ad Network

Option 1. SKAdNetwork Conversion Value Config API

Option 2. Decoded SKAdNetwork Postback