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?