> ## Documentation Index
> Fetch the complete documentation index at: https://help.airbridge.io/llms.txt
> Use this file to discover all available pages before exploring further.

# SKAdNetwork Integration Guide

This guide is intended to share how Airbridge and its partnered ad networks can be integrated with iOS's new [SKAdNetwork](https://developer.apple.com/documentation/storekit/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](https://developer.apple.com/documentation/storekit/skadnetwork/verifying_an_install_validation_postback)<br />(\* For version \< 2.0, set `NULL`) | SkAdNetwork Postback | string (nullable) |
| ad-network-id                  | true                                      | [SkAdNetwork Documentation](https://developer.apple.com/documentation/storekit/skadnetwork/verifying_an_install_validation_postback)                                          | SkAdNetwork Postback | string            |
| campaign-id                    | true<br />(\* For version 3.0 and before) | [SkAdNetwork Documentation](https://developer.apple.com/documentation/storekit/skadnetwork/verifying_an_install_validation_postback)                                          | SkAdNetwork Postback | integer           |
| source-identifier              | true<br />(\* For version 4.0 and later)  | [SkAdNetwork Documentation](https://developer.apple.com/documentation/storekit/skadnetwork/verifying_an_install-validation_postback)(\* For version \< 4.0, set `NULL`)       | SkAdNetwork Postback | string            |
| transaction-id                 | true                                      | [SkAdNetwork Documentation](https://developer.apple.com/documentation/storekit/skadnetwork/verifying_an_install_validation_postback)                                          | SkAdNetwork Postback | string            |
| app-id                         | true                                      | [SkAdNetwork Documentation](https://developer.apple.com/documentation/storekit/skadnetwork/verifying_an_install_validation_postback)                                          | SkAdNetwork Postback | integer           |
| attribution-signature          | true                                      | [SkAdNetwork Documentation](https://developer.apple.com/documentation/storekit/skadnetwork/verifying_an_install_validation_postback)                                          | SkAdNetwork Postback | string            |
| redownload                     | true<br />(\* For version 2.0 and later)  | [SkAdNetwork Documentation](https://developer.apple.com/documentation/storekit/skadnetwork/verifying_an_install_validation_postback)(\* For version \< 2.0, set `NULL`)       | SkAdNetwork Postback | boolean           |
| fidelity-type                  | true<br />(\* For version 2.2 and later)  | [SkAdNetwork Documentation](https://developer.apple.com/documentation/storekit/skadnetwork/signing_and_providing_ads)<br />- For version \< 2.2, set `NULL`)                  | SkAdNetwork Postback | integer           |
| did-win                        | true<br />(\* For version 3.0 and later)  | [SkAdNetwork Documentation](https://developer.apple.com/documentation/storekit/skadnetwork/receiving_ad_attributions_and_postbacks)<br />- For version \< 3.0, set `NULL`)    | SkAdNetwork Postback | boolean           |
| postback-sequence-index        | true<br />(\* For version 4.0 and later)  | [SkAdNetwork Documentation](https://developer.apple.com/documentation/storekit/skadnetwork/receiving_ad_attributions_and_postbacks)<br />- For version \< 4.0, set `NULL`)    | SkAdNetwork Postback | integer           |
| source-app-id                  | false                                     | [SkAdNetwork Documentation](https://developer.apple.com/documentation/storekit/skadnetwork/verifying_an_install_validation_postback)                                          | SkAdNetwork Postback | integer           |
| conversion-value               | true                                      | [SkAdNetwork Documentation](https://developer.apple.com/documentation/storekit/skadnetwork/verifying_an_install_validation_postback)                                          | SkAdNetwork Postback | integer           |
| coarse-conversion-value        | true<br />(\* For version 4.0 and later)  | [SkAdNetwork Documentation](https://developer.apple.com/documentation/storekit/skadnetwork/verifying_an_install-validation_postback)                                          | 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<br />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

```markdown cURL lines theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
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<br />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`

<Info>
  **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.
</Info>

## 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

<Note>
  **Checklist for Ad Network**

  `api_key` and `response_format` are unique values per Ad Network. Please contact the [Airbridge Platform team](mailto:platform@ab180.co) to receive yours.
</Note>

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

```json lines theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
{
  "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](/en/references/skadnetwork-configuration).

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

<link rel="alternate" hrefLang="en" href="https://help.airbridge.io/en/developers/integration-guide-skadnetwork" />