SKAdNetwork 미디어 파트너 연동

iOS 14 이상부터 지원하는 SkAdNetwork 기능을 사용하기 위해서는 매체(Ad Network)와 MMP(Airbridge)간 연동이 필요합니다.

SkAdNetwork Workflow

SkAdNetwork Workflow는 크게 3가지 단계에서 데이터의 이동이 이루어집니다.

  1. iOS Device => Ad Network (광고주 작업 필요)
  2. Ad Network => MMP
  3. MMP => Ad Network

본 가이드에서는 Ad Network가 수신한 SkAdNetwork 포스트백을 Airbridge로 전송할 수 있는 연동 방법 및 Airbridge에 고객사가 설정한 Conversion Value Configuration 에 따라 해석된 데이터를 미디어 파트너사로 재전송할 수 있는 방법에 대해서 안내합니다.

Ad Network → MMP 포스트백

Ad Network가 수신한 SkAdNetwork 포스트백을 Airbridge SKAN Postback API로 전달합니다. 아래 테이블에서 Source가 SkAdNetwork 포스트백 인 것은 받은 것을 가공 없이 그대로 전송하는 것이고, Source가 Ad Network인 것은 매체에서 SkAdNetwork 포스트백 정보를 decode하거나 부가적인 정보를 추가하여 전송하는 파라미터입니다.

Option 1. POST Method

이 방법은 iOS 기기에서 전달 받은 SKAdNetwork 포스트백을 POST 메소드를 통하여 Airbridge로 전송하는 방법입니다.

HTTP Protocol

Method

POST

Endpoint

https://postback.airbridge.io/skadnetwork/v1

Content-Type

application/json

Response

200: OK
400: Validation Error

Airbridge로 포스트백 전송 시에는 아래의 정보가 POST Body 내에 반드시 포함되어야 합니다. (테이블 참고)

필수항목:

  • SKAdNetwork Postback에 포함 된 모든 정보
  • 기여 매체(채널) 명 (attributed-channel)
  • 디바이스로부터 받은 IP 주소
  • iOS 디바이스에서 받은 Postback의 타임스탬프

선택항목:

  • 캠페인 파라미터

파라미터

필수 여부

설명

소스

Type

version

true

SkAdNetwork Documentation
(* version 2.0 미만의 경우, NULL 로 전송)

SkAdNetwork Postback

string (nullable)

ad-network-id

true

SkAdNetwork Documentation

SkAdNetwork Postback

string

campaign-id

true

SkAdNetwork Documentation

SkAdNetwork Postback

integer

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
(* version 2.0 이상)

SkAdNetwork Documentation
(* version 2.0 미만의 경우, NULL 로 전송)

SkAdNetwork Postback

boolean

fidelity-type

true
(* version 2.2 이상)

SkAdNetwork Documentation
(* version 2.2 미만의 경우, NULL 로 전송)

SkAdNetwork Postback

Integer

did-win

true
(* version 3.0 이상)

SkAdNetwork Documentation
(* version 3.0 미만의 경우, NULL 로 전송)

SkAdNetwork Postback

boolean

source-app-id

false

SkAdNetwork Documentation

SkAdNetwork Postback

integer

conversion-value

false

SkAdNetwork Documentation

SkAdNetwork Postback

integer

attributed-channel

true

Attributed Channel (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

iOS 기기에서 ad network가 포스트백을 수신한 시간. 13자리 UNIX 타임스탬프로 제공.

Ad Network

integer

예시

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

이 방법은 SKAdNetwork Postback을 수신하는 미디어 파트너사의 서버가 307 Redirect로 응답하여 Airbridge가 데이터를 수신하는 방법입니다.

HTTP Protocol

Method

307 Redirect

Endpoint

https://postback.airbridge.io/skadnetwork/v1

Response

200: OK
400: Validation Error

Redirect URL을 구성할 때, 아래 테이블의 정보를 참고하여 GET 파라미터에 추가하시길 바랍니다.

필수항목:

  • Attributed channel name (attributed-channel)

선택항목:

  • 캠페인 파라미터

파라미터

필수 여부

설명

소스

attributed-channel

true

Attributed Channel (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

예시

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

📘

Checklist for Ad Network

  • Required true인 파라미터들(테스트시 attribution-signiture 제외하고 전송)과 attributed campaign parameter들(ex. attributed campaign id)을 payload에 넣어 Airbridge Postback 서버(postback.airbridge.io)로 전송하여 200 response를 받는지 확인합니다.
  • conversion-value의 값에 따라 Step 3 포스트백에서 받는 결과가 달라지니 참고바랍니다.

MMP → Ad Network

Option 1. SKAdNetwork Conversion Value Config API

Ad Network가 SKAdNetwork Conversion Value Config API를 통해 고객사가 설정한 Conversion Value Config 정보를 받고, Conversion Value를 직접 decode 하는 방식입니다.

Query Parameters:

  • api_key
  • itunes_app_id ("Id"를 제외한 숫자값)
  • response_format

📘

Checklist for Ad Network

api_keyresponse_format은 Ad Network 별 고유값으로 Platform Manager에게 요청하여 발급 받을 수 있습니다.

Request 예시

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 예시

필드

설명

항상 포함 여부

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 (value range가 사용될 시에만 포함)

conversion_bits_rules.$.events.$.values.amount

The starting amount of the value range (equal to or greater than)

False (value range가 사용될 시에만 포함)

conversion_bits_rules.$.events.$.values.max_amount

The max amount of the value range (less than)

False (value range가 사용될 시에만 포함)

{
  "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
          }
        }
      ]
    }
  ]
}

SKAdNetwork Conversion Value Config API에 대한 자세한 내용은 API 가이드를 참고하세요.

Option 2. Decoded SKAdNetwork Postback

Ad Network로 부터 받은 SkAdNetwork Postback의 conversion value를 decode 하여 다시 Ad Network 측으로 전달하는 방식입니다. 해당 방식으로 진행하고자 하는 경우 Platform Team으로 문의 부탁드립니다.