Developer Docs
DashboardUser GuideDataspecStatus Page

Airbridge Integration Guide

Suggest Edits

본 가이드는 Airbridge와 미디어 파트너사간의 트래킹링크 및 포스트백 URL 연동에 대해서 안내합니다.
연동 시작에 앞서 아래 연동 요청 폼을 작성하여 보내주시면 빠르게 연동 담당자를 배정 후 자세한 프로세스를 안내해드리고 있습니다.

아래 가이드를 참고하여 트래킹 링크 템플릿 및 포스트백 URL을 구성하시기 바랍니다.

1. Tracking Link Template 설정

1) 기본 파라미터 추가

Airbridge의 Tracking Link를 통해 전달받을 수 있는 데이터의 종류는 다음과 같으며 필수 값이 존재합니다.

이름파라미터 이름필수 여부설명예시
Click IDclick_id필수터치포인트에 대한 매체사 측 고유 식별값click_id={Touchpoint_Id}
Publisher IDsub_id필수하위 네트워크 혹은 제휴 매체사 등을 나타내는 아이디sub_id={PUBLISHER_ID}
Sub Publisher IDsub_id_1
sud_id_2
sub_id_3		권장하위 네트워크의 또다른 하위 네트워크 아이디 (sub-sub publisher)
* 하위매체 순서(계층)에 맞게 사용해야 합니다.
( sub_id_1 > sub_id_2 > sub_id_3 )		sub_id_1={SUB_PUBLISHER_ID_1}
ADID (Android GAID 또는 iOS IDFA)ad_id가능한 경우 필수OS에 따른 광고 식별자
(Android의 ADID 혹은 iOS의 IDFA)
* gaid_raw, ifa_raw 두개의 구별된 파라미터 대신 하나의 파라미터만으로 광고 식별자를 전달할 시 사용		ad_id={ADID}
GAID (Android only)gaid_raw가능한 경우 필수Android에서 사용하는 광고 식별자 (ADID) (Google 공식 문서)gaid_raw={ANDROID_ADID}
IDFA (iOS only)ifa_raw가능한 경우 필수iOS 에서 사용하는 광고 식별자 (IDFA) (Apple 공식 문서)ifa_raw={IOS_IDFA}
IPipS2S 연동 및 Impression 연동 시 필수Tracking Link를 호출한 디바이스의 IP 주소ip={IP_ADDRESS}
User Agentuser_agentS2S 연동 및 Impression 연동 시 필수Tracking Link를 호출한 디바이스의 User Agentuser_agent={USER_AGENT}
Campaigncampaign선택캠페인 명campaign={CAMPAIGN}
Ad Groupad_group선택광고 그룹ad_group={AD_GROUP}
Ad Creativead_creative선택광고 소재ad_creative={AD_CREATIVE}
Termterm선택키워드term={KEYWORD}
Campaign IDcampaign_id선택캠페인 IDcampaign_id={CAMPAIGN_ID}
Ad Group IDad_group_id선택광고 그룹 IDad_group_id={AD_GROUP_ID}
Ad Creative IDad_creative_id선택광고 소재 IDad_creative_id={AD_CREATIVE_ID}
Term IDterm_id선택키워드 IDterm_id={TERM_ID}

📘

Tracking Link 내 ADID 추가 권장

현재 트래킹 링크 템플릿 속의 ADID는 필수값은 아니지만, iOS 14.5 업데이트 정책으로 핑거프린팅이 불가해짐으로서 ATT(AppTrackingTransparency) 프레임워크를 통해 옵트인을 한 사용자의 IDFA값을 최대한 활용하여 어트리뷰션을 할 수있도록 해당 파라미터를 추가를 권장드립니다.

Airbridge의 Tracking Link에 필수로 추가가 필요한 매크로는 매체사 측의 'Click ID', 'Publisher ID' 로, 해당 매크로들을 포함한 매체사 측에서 제공 가능한 매크로 리스트나 별도 문서가 있는 경우 저희에게 공유해주시면, 내부적으로 Tracking Link Template을 구성하여 시스템에 등록하도록 하겠습니다.

예시)
https://abr.ge/@APP_NAME/MEDIA_NAME?click_id={CLICK_ID}&sub_id={SUB_ID}&gaid_raw={GAID}&ifa_raw={IDFA}

2) 커스텀 파라미터 추가

위 안내된 파라미터 외에도 터치포인트 발생 시 매체사 측의 특정 데이터를 수집하고 추후에 Postback으로 돌려받기를 원하는 값이 있을 경우 Tracking Link Template에 커스텀으로 파라미터를 추가할 수 있으며, 커스텀 파라미터의 Key값은 매체사 측에서 원하시는 값으로 추가해주시면 됩니다.

예시)
https://abr.ge/@APP_NAME/MEDIA_NAME?click_id={CLICK_ID}&sub_id={SUB_ID}&gaid_raw={GAID}&ifa_raw={IDFA}&custom_param1={MACRO1}&custom_param2={MACRO2}

3) Tracking Link 동작

클릭 혹은 조회용 Tracking Link 호출 시 매체사 측에서는 사전에 협의 된 트래킹 URL내의 매크로에 실제 값을 채워서 데이터를 송신(Tracking Link URL을 호출)하게 됩니다. 아래 예시를 참고하시기 바랍니다.

[Tracking Link URL Template 및 실제 호출]
https://abr.ge/@airbridge/ab180_ads?click_id={TOUCHPOINT_ID}&ad_id={ADID}&sub_id={PUBLISHER_ID}→
https://abr.ge/@airbridge/ab180_ads?click_id=abcf15142ads&ad_id=94ec0320-7f08-11e6-bdf4-0800200c9a6 6&sub_id=abzdo_16345

2. Postback URL Template 설정

매체사는 Airbridge 고객사가 대시보드 내에서 설정한 채널별 Postback 전송 옵션 설정(기여 여부 및 신규 이벤트 여부에 따른 Postback 전송)에 따라서 Airbridge에서 트래킹한 고객사 서비스의 이벤트 및 Attribution 관련 정보를 Postback을 통해 실시간으로 전달 받을 수 있습니다.
Postback 수신을 위해 매체사에서는 아래와 같이 이벤트 종류별로 각각의 Postback URL Template을 Airbridge 시스템에 등록해야 합니다.

  1. 설치(install) 용 Postback URL Template
  2. 인앱 이벤트(In-app Events) 용 Postback URL Template

만약 이벤트 종류별로 Postback URL Template이 동일하다면 한개의 Postback URL Template만 구성하여 전달해주시면 됩니다. Postback URL Template 구성을 위한 상세 스펙은 아래 내용을 참고 부탁드립니다.

1) Airbridge 이벤트 종류

Airbridge에서 Postback으로 제공 가능한 이벤트는 'Airbridge 기본 이벤트(Standard Event)'와 '고객사별 커스텀 이벤트(Custom Event)'로 나눠집니다.

Event TypeEventsEvent Name (raw)
Standard Eventinstall (설치)app_install
Standard EventLaunch / Open (실행)app_open
Standard EventDeeplink Launch (딥링크 실행)app_deeplink_open
Standard EventSign Up (회원 가입)airbridge.user.signup
Standard EventSign In (로그인)airbridge.user.signin
Standard EventSign Out (로그아웃)airbridge.user.signout
Standard EventView Home (홈화면 조회)airbridge.ecommerce.home.viewed
Standard EventView Product List (상품 리스트 조회)airbridge.ecommerce.productList.viewed
Standard EventView Search Result (검색 결과 조회)airbridge.ecommerce.searchResults.viewed
Standard EventView Detailed Product (상품 상세페이지 조회)airbridge.ecommerce.product.viewed
Standard EventAdd To Cart (장바구니 담기)airbridge.ecommerce.product.addedToCart
Standard EventPurchase (구매완료)airbridge.ecommerce.order.completed
Standard EventAd Impression (광고 노출)airbridge.adImpression
Standard EventSubscribe (구독)airbridge.subscribe
Standard EventUnsubscribe (구독 취소)airbridge.unsubscribe
Standard EventSchedule (일정 예약)airbridge.schedule
Standard EventUnlock Achievement (과제 달성)airbridge.unlockAchievement
Standard EventAd Click (광고 클릭)airbridge.adClick
Standard EventAdd to Wishlist (위시리스트 추가)airbridge.addToWishlist
Standard EventShare (공유)airbridge.share
Standard EventComplete Tutorial (튜토리얼 완료)airbridge.completeTutorial
Standard EventAchieve Level (레벨 달성)airbridge.achieveLevel
Standard EventAdd Payment Info (결제 수단 등록)airbridge.addPaymentInfo
Standard EventInitiate Checkout (결제 시작)airbridge.initiateCheckout
Standard EventSpend Credits (크레딧 사용)airbridge.spendCredits
Standard EventStart Trial (체험판 시작)airbridge.startTrial
Standard EventRate (평가)airbridge.rate
Custom Event고객사별 상이고객사별 상이

설치 이벤트부터 구매 완료 이벤트까지는 Airbridge에서 제공하는 기본 이벤트(Standard Event)로, 모든 고객사에서 공통적으로 사용하는 이벤트 목록입니다.

Postback 전송 시 각 이벤트에 대해서 매체사측에서 전달받기를 원하는 별도의 이벤트명이나(예를 들어 회원가입 이벤트에 대해서 'airbridge.user.signup' 대신 'Registration'로 전달) 특정 이벤트를 의미하는 ID값('airbridge.user.signup' 대신 숫자 아이디 7)이 있는 경우 각 이벤트별로 맵핑 테이블을 전달해주시면 해당 값으로 전송할 수 있으며, 별도 원하시는 값이 없다면 위 표의 'Event Name (raw)'에 표기된 값으로 전달됩니다.

커스텀 이벤트(Custom Event)는 고객사 서비스별로 설정 및 트래킹하는 이벤트로, 고객사마다 다른 인앱 이벤트명을 사용하고 있으며, 고객사 설정값이 그대로 Postback URL의 이벤트명으로 전송됩니다. 만약 고객사의 커스텀 이벤트도 다른 값으로 변환하여 전송이 필요한 경우 별도 요청 부탁드리겠습니다.

2) Postback URL Template 내 지원 데이터 및 매크로

Airbridge에서 Postback URL을 통해 제공하는 데이터의 종류는 아래 Airbridge Postback Spec 시트에서 확인할 수 있습니다.

Postback을 통해 전달받고자 하는 데이터는 'Postback Spec' 시트에서 플랫폼별 이벤트에 따라(Web 이벤트 또는 App 이벤트) 'Web' 또는 'App' 컬럼이 '1'로 표기된 항목들을 참고하시면 되며, 해당 데이터를 Postback URL Template 내에 추가 시에는 'Field Value' 열의 값을 중괄호('{','}')로 감싼 매크로 형태로 사용해주시면 됩니다. 예를 들어 Postback을 통해 Airbridge Device ID 값을 전달받기 위해서는 '{device.deviceUUID}' 를 매체사의 'Key 값'과 맵핑합니다.

3) Postback URL Template 내 필수 포함 파라미터 (필수)

혹시 모를 중복 전송 방지 및 이슈 발생 시 원활한 트러블슈팅을 위해 Postback URL 내 하기 두 파라미터는 필수적으로 추가해야 합니다.

  • a) Postback을 통해 이벤트 발생 시간 데이터를 수집하는 경우 매체측 파라미터와 맵핑하여 Postback URL에 추가해야하며, 만약 이벤트 발생 시간 데이터를 수집하지 않는다 하더라도 'event_timestamp={eventTimestamp}' 와 같이 관련 파라미터를 임의로 추가한 후 매체측 내부 시스템에서 해당 파라미터로 인해 에러가 발생하지 않도록 작업이 필요합니다.
이름타입파라미터 이름
이벤트 발생시간string{eventDatetime}
이벤트 발생시간 (GMT or UTC기준)string{eventDatetimeGMT}
이벤트 발생시간 (ms since Epoch) - 13자리int{eventTimestamp}
이벤트 발생시간 (s since Epoch) - 10자리int{eventTimestampInSec}
  • b) Postback을 통해 Device Identifier을 수집하는 경우 매체측 파라미터와 맵핑하여 Postack URL에 추가해야하며, 만약 웹 지면 보유 등으로 디바이스 식별자를 수집하지 않는다 하더라도, {device.deviceUUID} & {device.DeviceUUIDType} 혹은 {device.gaid} & {device.ifa}파라미터로 인해 매체측 내부 시스템에서 에러가 발생하지 않도록 작업이 필요합니다. * deviceUUID는 총 4가지 타입의 DeviceID(GAID,IDFA,IDFV,Random Generated)가 인입될 수 있으므로, deviceUUIDType 매크로도 함께 추가해주시기 바랍니다.
이름타입파라미터 이름
Airbridge Device IDstring{device.deviceUUID}
Airbridge Device ID Typestring{device.deviceUUIDType}
GAIDstring{device.gaid}
IDFAstring{device.ifa}

4) 제품 관련 이벤트의 상품 데이터

장바구니 담기, 구매 완료와 같이 제품(Product)과 관련된 이벤트의 경우 여러개의 제품 데이터가 존재할 수 있습니다. 이러한 복수개의 제품 데이터를 Postback을 통해 JSON 형태로 전달받을 수 있습니다.
Postback URL Template에는 JSON 형태의 여러 제품 데이터를 전달받기 위한 매체측의 파라미터 키(Key)에 {@postback.jsonData}를 맵핑하여 추가하고, JSON 내에서 전달받고자하는 제품 관련 데이터를 맵핑하여 Postback URL Template 과 함께 전달 부탁드립니다. 대괄호, 중괄호 등의 JSON 형태와 관련된 문법적인 요소는 매체측 내부 포맷에 따라 자유롭게 설정 가능합니다.
또한 템플릿을 구성하실 때는 JSON 데이터에서 반복되는 부분과 그렇지 않은 부분을 명확하게 나누기 위하여 {@for ... in ...} 문법을 사용합니다.
아래 예시에서와 같이 템플릿의 {@for product in eventData.goal.semanticAttributes.products} 와 {@endfor} 사이가 반복됩니다. 각각의 상품에는 {product.}로 접근 가능하며, {product.}으로 사용할 수 있는 값은 아래 테이블을 참고해주시기 바랍니다.

이름타입파라미터 이름
Product IDstringeventData.goal.semanticAttributes.product[0].productID
Product NamestringeventData.goal.semanticAttributes.product[0].name
Product PricefloateventData.goal.semanticAttributes.product[0].price
Product QuantityinteventData.goal.semanticAttributes.product[0].quantity
Product CurrencystringeventData.goal.semanticAttributes.product[0].currency
Product PositioninteventData.goal.semanticAttributes.product[0].position

예시) ...&product_info={@postback.jsonData}&...
예시) {@postback.jsonData} 로 전달될 JSON Template 

[ 
{@for product in eventData.goal.semanticAttributes.products} 
	{ 
		"event_item_id": {product.productID}, 
		"quantity": {product.quantity}, 
		"unit_price": {product.price}, 
		"currency_code": {product.currency}, 
		"event_item_name": {product.name} 
	}, 
{@endfor} 
]

5) Postback URL 동작

Airbridge가 고유의 기여 모델을 통해서 전환 이벤트 발생에 기여한 터치 포인트를 선정한 후, Airbridge는 사전에 매체와 합의된 Postback URL에 값을 채워서 최종적으로 전환과 관련된 데이터를 매체 측에 전송하게 됩니다.
이 때, 커스텀 파라미터의 경우 포스트백 URL을 구성할 시 해당 파라미터가 트래킹 링크 파라미터임을 구분하기 위해 @trackingLink. prefix를 붙여 사용해야 합니다. (예: {@trackingLink.custom_param}) 아래 예시를 참고 하시기 바랍니다.

[Postback URL Template 및 실제 호출]
https://api.example-ad-channel.com/postback/airbridge?touchpoint_id={attributionResult.attributedClickID}& ad_channel={attributionResult.attributedChannel}&event_timestamp={eventTimestamp}&customID={@trackin gLink.custom_param}
→
https://api.example-ad-channel.com/postback/airbridge?touchpoint_id=e7580180-7f04-11e6-bdf4-0800200c 9a66&ad_channel=sample_channel&event_timestamp=1479186394000&customID=4093721


자주 묻는 질문

  1. Timestamp를 초 단위로 변환하고 싶은데 가능한가요?
    ⇒ Airbridge의 모든 타임스탬프 필드는 기본적으로 millisecond 단위입니다. 이를 second 단위로 변환 하기 위해서는 변환하고자 하는 타임스탬프 필드값에 InSec을 붙여 간단하게 변환 할 수 있습니다. (예: {requestTimestamp} → {requestTimestampInSec})

  2. boolean 타입 필드를 int 타입으로 변환할 수 있나요?
    ⇒ Airbridge Postback Spec 시트에 나와있는 필드값 중 boolean 타입을 갖는 필드에 한해서 :int를 붙여 타입을 변환할 수 있습니다. true는 1, false는 0으로 변환됩니다.
    (예: {@postback.isAttributedToTargetChannel} → {@postback.isAttributedToTargetChannel:int})
    매체 연동과 관련하여 추가적인 문의사항이 있는 경우 Airbridge Platform팀([email protected])으로 문의하시길 바랍니다.

Updated about 2 years ago