User GuideDeveloper GuideAPI
Dashboard

SKAdNetwork Integration Guide

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.

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

  2. Ad Network → Airbridge

  3. 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

false

SkAdNetwork Documentation

SkAdNetwork Postback

integer

coarse-conversion-value

false

SkAdNetwork Documentation

SkAdNetwork Postback

string

attributed-channel

true

Attributed Channel (Registered Name on Airbridge)

Ad Network

string

attributed-campaign

false

Attributed Campaign

Ad Network

string

attributed-campaign-id

false

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

true

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)

  • IP address received from the device

  • The timestamp of the postback sent from the iOS device

Optional:

  • Campaign Parameters

Example

cURL
123456789101112131415161718
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

false

Attributed Campaign

Ad Network

attributed-campaign-id

false

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 Networks

Transmit 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 Network

api_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)

1234567891011121314151617181920212223242526272829303132333435363738
{
  "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.

Was this page helpful?

Have any questions or suggestions?