들어가며
이번 문서에서는 에어브릿지 SDK의 설치와 활용 방법에 대해 다룹니다. SDK 설치는 앱의 성과 추적, 딥링크 설정, 이벤트 전송을 포함하여, 에어브릿지의 핵심 기능을 원활하게 활용하기 위해 필수적인 단계입니다. 각 단계별로 필요한 설정과 주의사항을 짚어드리니, SDK 설치와 연동 작업을 순서대로 진행해 주세요.
2.1 에어브릿지 기본 SDK 설치하기
먼저, 아래 개발자 가이드를 참고하여 개발 언어에 맞는 에어브릿지 SDK를 설치해 주세요. SDK 설치에 필요한 앱 이름과 SDK 토큰은 에어브릿지 대시보드의 Settings > Tokens 탭에서 확인할 수 있습니다.
▶ 에어브릿지 SDK 시작하기: 에어브릿지 SDK가 지원하는 개발 언어를 확인하고, 적절한 SDK를 설치합니다.
▶ 토큰 확인하기: 에어브릿지 대시보드에서 앱 이름과 토큰 이름을 확인하는 방법을 안내합니다.
에어브릿지 SDK는 디바이스 정보(디바이스 모델, OS Version) 및 앱 버전 등의 데이터를 자동으로 수집합니다. 자세한 항목은 가이드를 참고해주세요.
2.2 iOS IDFA 수집 작업하기
iOS에서 설치(Install) 이벤트를 전송할 때, 앱 추적 팝업(ATT Prompt)을 허용한 유저의 IDFA를 획득하려면 다음 설정이 필요합니다. 수집된 IDFA는 디바이스 ID 매칭을 통한 기여에 사용되므로 꼭 설정을 완료해주세요. 반대로, Restricted SDK를 사용하는 등 ADID를 수집하지 않는 경우에는 이 작업을 생략해도 됩니다.
▶ Tracking Authorize Prompt 설정: AppTrackingTransparency.framework를 사용해 앱 추적 허용 선택창(ATT Prompt)을 띄워 유저의 동의를 받습니다.
개발자 가이드 바로가기
2.3 딥링크 설정하기
유저가 에어브릿지 트래킹 링크를 클릭했을 때 앱 내 상세 페이지로 랜딩할 수 있도록 Airbridge.handleDeeplink 함수를 활용하여 딥링크 화면 이동을 구현합니다.
에어브릿지 트래킹 링크는 앱링크(App Links) 또는 유니버셜 링크(Universal Links)로 앱 실행을 우선 시도하며, 실패 시 스킴 딥링크 방식으로 앱을 실행합니다. 앱이 어떤 방식으로 열리더라도 에어브릿지 SDK는 Airbridge.handleDeeplink 함수를 통해 스킴 딥링크 주소를 앱에 전달합니다.
따라서 개발팀에서는 Airbridge.handleDeeplink를 통해 전달받은 스킴 딥링크 주소를 기준으로 앱 내 화면 이동 로직을 구현하면 됩니다.
iOS에서 Autofill 기능을 위한 Webcredentials 도메인 추가 방법
iOS의 경우 보안을 위해 Autofill 기능(암호 저장 기능)을 사용하려면, 유저의 비밀번호를 안전하게 보관할 수 있도록 Webcredentials 도메인 추가 작업이 필요합니다. 자세한 사항은 아래 가이드를 참고해주세요.
개발자 가이드 바로가기
2.4 이벤트 전송하기
앱 내에서 발생하는 전환 성과를 측정하고 리타겟팅 캠페인을 집행하기 위해 필요한 이벤트를 전송해 주세요. 전송할 이벤트와 하위 프로퍼티는 마케터가 정의한 이벤트 택소노미를 참고하시기 바랍니다.
자주 묻는 질문
아니요, 사용자 식별자 설정은 필수는 아닙니다. 그러나 다음과 같은 경우에는 설정을 고려해보실 수 있습니다. 또한, 보안을 위해 사용자 식별자는 해시화하여 전송하는 것이 좋습니다.
내부 이벤트 분석: 에어브릿지 이벤트를 내부 사용자 ID 기준으로 분석하려는 경우
서드파티 연동: 일부 서드파티 솔루션은 사용자 ID를 기준으로 이벤트를 수집하므로, 회원 유저와의 연결이 필요하다면 설정할 수 있습니다.
네, 간편 로그인(예: 네이버, 카카오)이나 간편 결제 서비스(예: 네이버페이, 카카오페이)를 사용하는 경우, 이벤트를 안정적으로 전송하기 위해서는 유저가 다른 페이지로 이동한 후 다시 돌아와 페이지가 로드된 시점에 이벤트를 수집하는 것이 좋습니다. 이는 창이 여러 번 이동하는 과정에서 이벤트 전송이 실패할 가능성이 있기 때문입니다.
예를 들어, 유저가 네이버 페이로 결제를 진행할 때, 결제 페이지가 로드되는 사이가 아니라 유저가 결제를 완료하고 다시 앱으로 돌아와 주문서 페이지가 완전히 로드된 후에 이벤트를 전송하는 것이 안전합니다.
웹뷰에서 발생하는 이벤트는 에어브릿지에서 앱(App) 이벤트로 인식되도록 설정해야 합니다. 이를 위해 에어브릿지는 하이브리드 앱 설정을 통해 웹뷰 이벤트를 처리할 수 있는 Bridge Function을 제공합니다.
웹뷰에서 발생하는 이벤트가 앱 이벤트로 올바르게 전송되도록 하려면, 다음과 같은 개발 언어별 설정 방법을 참고해 주세요.
▶ Android, iOS, Flutter, React Native, Unity: 웹페이지에 에어브릿지 Web SDK를 설치한 후, 해당 SDK로 이벤트를 전송하고 웹뷰 영역에 하이브리드 앱 설정을 적용해 주세요.
Android: 하이브리드 앱 설정
iOS: 하이브리드 앱 설정
Flutter: 하이브리드 앱 설정
React Native: 하이브리드 앱 설정
Unity: 하이브리드 앱 설정
참고로, 웹뷰에서 전송한 앱 이벤트는 QA할 때 ‘웹 이벤트 실시간 로그(Web Real-time log)’가 아닌, ‘앱 이벤트 실시간 로그(App Real-time log)’에 기록되어야 합니다.
마케터가 사전에 고려하여 설정한 이벤트 택소노미에 따라 작성된 프로퍼티들을 수집하는 것을 권장합니다.다만 이벤트 별로 반드시 누락되어서는 안 되는 프로퍼티를 아래에 안내드리니, 해당 프로퍼티들을 반드시 포함시켜 주시기 바랍니다. 아래 이벤트들을 수집하지 않을 경우 고려하지 않아도 됩니다.
이벤트명:
airbridge.ecommerce.order.completed구매액:
eventData.value리포트에서 구매액을 확인하기 위해 사용됩니다.
통화 정보 (KRW, USD 등):
eventData.goal.semanticAttributes.currency광고 미디에이션 솔루션을 사용하면 인앱 광고로 벌어들인 수익이 미국 달러(USD)로 수집됩니다. 이를 대시보드의 앱 기준 통화로 변환하기 위해서는 이벤트에 통화 정보가 수집되어야 합니다.
Applovin Max, Google Admob, Unity Levelplay Mediation를 사용한다면 미디에이션 플랫폼 연동하기에서 예시 코드를 참고할 수 있습니다.
기준 통화는 영문 대문자 3자리입니다 (예: KRW, USD 등).
eventData.goal.semanticAttributes.currency로 전송해 주세요. (eventData.goal.semanticAttributes.products.$0.currency가 아닙니다.)
주문번호:
eventData.goal.semanticAttributes.transactionID추후 동일한 주문번호로 들어온 이벤트를 중복 제거할 수 있습니다.
이벤트명:
airbridge.ecommerce.order.canceled주문번호:
eventData.goal.semanticAttributes.transactionID취소가 아닌 구매 완료 시점의 주문번호를 전송해 주세요.
이벤트명:
airbridge.adImpression통화 정보 (KRW, USD 등):
eventData.goal.semanticAttributes.currency광고 미디에이션 솔루션을 사용하면 인앱 광고로 벌어들인 수익이 미국 달러(USD)로 수집됩니다. 이를 대시보드의 앱 기준 통화로 변환하기 위해서는 이벤트에 통화 정보가 수집되어야 합니다.
Applovin Max, Google Admob, Unity Levelplay Mediation를 사용한다면 미디에이션 플랫폼 연동하기에서 예시 코드를 참고할 수 있습니다.
기준 통화는 영문 대문자 3자리입니다 (예: KRW, USD 등).
eventData.goal.semanticAttributes.currency로 전송해 주세요. (eventData.goal.semanticAttributes.products.$0.currency가 아닙니다.)
개발자 가이드 바로가기
2.5 추가 SDK 설정 작업하기
에어브릿지는 기본 광고 성과 추적 기능 외에도 앱 삭제 이벤트 트래킹 등 다양한 추가 기능을 제공합니다. 본 안내서의 ‘1. 에어브릿지 도입 준비하기 > 추가 기능 개발 작업 필요 여부 결정하기'에서 마케팅 팀과 협의한 추가 개발 작업을 완료해 주세요.
2.6 SDK 테스트 진행하기
모든 SDK 설치 작업이 완료되었다면, 딥링크 설정, 이벤트 수집 설정, 사용자 식별자 전송 설정 등이 정상적으로 진행되는지 점검해 주세요. 추가 SDK 설정 작업을 진행한 경우, 해당 작업도 함께 점검해 주시기 바랍니다. 자세한 점검 사항은 아래 가이드를 참고해 주세요.
2.7 앱 배포하기
SDK 테스트까지 완료되었다면, SDK가 설치된 앱을 앱 마켓에 배포해 주세요.
자주 묻는 질문
에어브릿지 유저 가이드의 앱마켓 심사 준비하기에서 확인하실 수 있습니다.
다음 단계 안내
이상으로 에어브릿지 SDK 설치와 설정 작업이 완료되었습니다. 에어브릿지 SDK가 설치된 앱이 앱 마켓에 배포되었다면 다음 단계인 광고 성과 측정을 위한 에어브릿지 대시보드 사용 시작하기로 넘어가 주세요.