# AdBrix 딥링크 설정
AdBrix 콘솔 광고 랜딩 설정, iOS/Android URI Scheme 처리, Universal Link/App Link 선택 적용 기준.
- 카테고리: AdBrix
- 소요 시간: 약 10분
- 난이도: 중간
- 업데이트: 2026.05.21
- 원문: /wiki/playbook/adbrix/how-to-set-up-adbrix-deeplinks
## 목차
- [이 문서의 목적](#purpose)
- [1단계 · 콘솔 광고 랜딩 설정](#step-1)
- [2단계 · iOS URI Scheme 처리](#step-2)
- [3단계 · Android URI Scheme 처리](#step-3)
- [4단계 · App Link와 Universal Link 적용 기준](#step-4)
- [5단계 · WebView 라우터](#step-5)
- [6단계 · Deferred Deep Link](#step-6)
- [참고 링크](#references)
- [자주 묻는 질문](#faq)
AdBrix 딥링크는 앱에 이미 구현된 URI Scheme 또는 도메인 기반 딥링크를 트래킹 링크와 연결하는 작업입니다. 앱 개발팀은 OS가 앱을 열 수 있도록 진입점을 만들고, AdBrix SDK에는 열린 URL을 전달해야 합니다. AdBrix는 앱에 없는 딥링크를 새로 만들어 주는 도구가 아니라, 트래킹 링크 클릭과 앱 내부 라우팅을 이어 주는 역할입니다.
> **이 문서 핵심**
>
> - SDK 초기화가 먼저 완료되어 있어야 합니다.
>
> - 빠른 시작은 URI Scheme 등록만으로도 가능합니다.
>
> - Universal Link/App Link는 AdBrix 트래킹 링크 도메인을 쓸지, 고객사 자체 도메인을 쓸지 먼저 결정합니다.
## 1단계. 콘솔에서 광고 랜딩 설정
[AdBrix 콘솔](https://console.adbrix.ai/)에서성과 측정 → 성과 측정 설정 → 광고 랜딩 설정으로 이동합니다. 트래킹 링크를 만들기 전에 Android와 iOS 랜딩 정보를 먼저 입력해야 링크가 정상 동작합니다.
> **화면 1.** 성과 측정 메뉴에서 설정 영역으로 이동합니다.
> **화면 2.** 트래킹 링크 생성 전 광고 랜딩 설정을 먼저 채웁니다.
> **화면 3.** Android 예비 랜딩 주소, 딥링크 스킴, 패키지 이름을 입력합니다.
> **화면 4.** iOS 예비 랜딩 주소, 딥링크 스킴, 앱스토어 ID를 입력합니다.
> **화면 5.** 필수값이 누락되면 validation이 표시되고 저장이 막힙니다.
> **화면 6.** 저장 시 로그인 이메일 확인을 거쳐 최종 반영합니다.
## 2단계. iOS URI Scheme 처리
`Info.plist` 또는 Xcode URL Types에 앱의 scheme을 등록합니다. 콘솔에 입력한 딥링크 스킴과 대소문자까지 정확히 일치해야 합니다.
**Info.plist**
```xml
CFBundleURLTypes
CFBundleURLName
com.example.app
CFBundleURLSchemes
yourapp
```
앱이 URI Scheme으로 열리면 받은 URL을 SDK의 `deepLinkOpen`으로 전달합니다.
**AppDelegate.swift**
```swift
func application(_ app: UIApplication,
open url: URL,
options: [UIApplication.OpenURLOptionsKey: Any] = [:]) -> Bool {
Adbrix.shared().deepLinkOpen(url: url)
return true
}
```
## 3단계. Android URI Scheme 처리
랜딩 Activity에 intent-filter를 추가합니다. `android:scheme` 값은 콘솔의 딥링크 스킴과 같아야 합니다.
**AndroidManifest.xml**
```xml
```
> **주의**
>
> Activity가 `singleTop` 또는 `singleTask`라면 `onNewIntent`에서 `setIntent(intent)`를 호출해야 SDK가 최신 URL을 읽을 수 있습니다.
**MainActivity.kt**
```kotlin
override fun onNewIntent(intent: Intent) {
super.onNewIntent(intent)
setIntent(intent)
}
```
## 4단계. App Link와 Universal Link 적용 기준 정리
URI Scheme만으로도 트래킹 링크 진입은 동작합니다. App Link와 Universal Link는 링크 클릭 시 OS가 `https://...` 주소를 앱으로 직접 넘기게 만드는 선택 작업입니다. 핵심은 AASA/`assetlinks.json`을 항상 고객사가 호스팅하는 게 아니라는 점입니다.
| 사용 방식 | 도메인 예시 | AASA / assetlinks 호스팅 | 적용 기준 |
| --- | --- | --- | --- |
| URI Scheme | `yourapp://...` | 해당 없음 | 가장 먼저 적용 |
| AdBrix 원본 트래킹 링크 도메인 | `click2.igaworks.com` | 해당 없음 | Universal/App Link 직접 검증 대상이 아님 |
| AdBrix 대표 도메인 | `your-domain.com`, `brand.ab-x.link` | 콘솔 도메인 설정 기준 | Universal/App Link를 쓸 때 앱에 등록 |
| 고객사 자체 도메인 | `link.your-brand.com` | 고객사 서버에서 직접 호스팅 | 브랜드 도메인으로 직접 App Link/Universal Link를 열 때 |
> **주의**
>
> AASA 또는 `assetlinks.json`을 고객사 웹 서버에 올리는 작업은 고객사 자체 도메인으로 Universal Link/App Link를 열 때만 해당합니다. AdBrix 콘솔에서 만든 ABX 도메인 또는 대표 도메인을 쓰는 경우에는 콘솔의 도메인 설정과 앱 설정의 도메인 값이 일치하는지 확인하는 흐름으로 봅니다.
커스텀 도메인을 쓰는 경우에는 성과 측정 설정 → 도메인 설정에서 ABX 도메인 또는 브랜드 도메인을 준비하고 대표 도메인으로 적용합니다. 이미 발급된 트래킹 링크에 영향을 줄 수 있으므로 저장 전 앱 매니페스트와 Associated Domains 등록 값을 먼저 맞춥니다.
> **화면 7.** 도메인 설정에서 트래킹 링크 대표 도메인을 관리합니다.
> **화면 8.** 새 ABX 도메인 또는 브랜드 도메인을 생성합니다.
> **화면 9.** ABX 도메인 값을 입력합니다.
> **화면 10.** 입력한 도메인을 저장합니다.
> **화면 11.** 도메인 생성 완료 상태를 확인합니다.
> **화면 12.** 트래킹 링크에 사용할 대표 도메인을 선택합니다.
> **화면 13.** 대표 도메인 변경 전 영향 범위를 확인합니다.
> **화면 14.** 로그인 이메일 입력으로 변경을 확정합니다.
> **화면 15.** 대표 도메인이 적용된 상태를 확인합니다.
### iOS Universal Link
Xcode의 Signing & Capabilities → Associated Domains에 콘솔에서 대표 도메인으로 설정한 Universal Link 도메인을 추가합니다. 공식 iOS 가이드 기준으로 원본 트래킹 링크 도메인은 Universal Link 대상으로 쓰지 않고, 커스텀/ABX 도메인을 대표 도메인으로 설정한 뒤 앱에 등록합니다.
**Associated Domains**
```text
applinks:your-domain.com
applinks:brand.ab-x.link
```
Universal Link로 앱이 열리면 URI Scheme과 마찬가지로 URL을 SDK에 전달합니다.
**AppDelegate.swift**
```swift
func application(_ application: UIApplication,
continue userActivity: NSUserActivity,
restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,
let url = userActivity.webpageURL else {
return false
}
Adbrix.shared().deepLinkOpen(url: url)
return true
}
```
### Android App Link
Android App Link는 선택 기능입니다. 사용할 경우 랜딩 Activity에 `https` intent-filter를 추가하고, `host`는 콘솔에서 대표 도메인으로 설정한 도메인과 맞춥니다.
**AndroidManifest.xml**
```xml
```
> **주의**
>
> 공식 Android 가이드는 App Link 사용 시 트래킹 링크의 딥링크 패스 방식을 `동적 패스`로 설정하고, 생성된 링크의 `deeplink_custom_path`에 이동할 딥링크 path를 전달하라고 안내합니다. 또한 App Link 진입 intent에 자동으로 붙는 `is_used_abx_applink=true` 값을 임의로 수정하면 광고 성과 측정이 정확하지 않을 수 있습니다.
> **화면 16.** 광고 랜딩 설정에서 App Link/Universal Link 값을 입력합니다.
> **화면 17.** Android App Link 검증에 필요한 SHA-256 인증서 지문을 확인합니다.
> **화면 18.** Android SHA-256 값을 콘솔에 입력합니다.
> **화면 19.** iOS Universal Link 설정 영역을 확인합니다.
> **화면 20.** Application Identifier를 Team ID와 Bundle ID 기준으로 입력합니다.
### 트래킹 링크 파라미터 기준
AdBrix 트래킹 링크는 고정 딥링크와 동적 딥링크를 구분합니다. 여러 상세 페이지를 하나의 트래킹 링크 형식으로 처리해야 하면 동적 방식을 쓰고, 매체 또는 파트너가 아래 파라미터에 실제 이동 주소를 URL 인코딩해서 전달합니다.
| 파라미터 | 용도 | 주의사항 |
| --- | --- | --- |
| `abx_deeplink_url` | URI Scheme 기반 동적 딥링크 path | URL 인코딩 필요 |
| `abx_applink_url` | Android App Link로 열 HTTP URL | URL 인코딩 필요 |
| `abx_univ_url` | iOS Universal Link로 열 HTTP URL | URL 인코딩 필요 |
| `deeplink_custom_path` | Deferred Deep Link 또는 App Link 동적 path | 콘솔 설정과 함께 검증 |
## 5단계. WebView 라우터에서 최종 URL로 변환
WebView 앱은 SDK 콜백으로 받은 딥링크 값을 WebView가 로드할 실제 HTTPS URL로 바꿔야 합니다. 일반 네이티브 앱은 `product/123` 같은 path로 화면 라우터를 호출하면 되지만, WebView 앱은 같은 path를 웹 호스트 URL로 합성한 뒤 `WKWebView.load` 또는 `WebView.loadUrl`을 호출해야 합니다.
| 입력 예시 | WebView 로드 URL | 처리 기준 |
| --- | --- | --- |
| `yourapp://product/123?ref=ad` | `https://your-brand.com/product/123?ref=ad` | scheme 제거 후 path/query 유지 |
| `/product/123?ref=ad` | `https://your-brand.com/product/123?ref=ad` | path만 온 경우 그대로 합성 |
| AdBrix click URL | 로드하지 않음 | SDK가 처리해야 하는 값이므로 앱 라우터에서 직접 분해하지 않음 |
> **팁**
>
> 딥링크 설정은 “앱을 여는 일”과 “열린 뒤 어느 WebView URL로 이동할지”를 분리해서 검증해야 합니다.
> **주의**
>
> 라우터는 허용된 웹 호스트만 로드해야 합니다. 딥링크 값에 외부 `https://` URL이 섞여 들어왔을 때 그대로 WebView에 로드하면 오픈 리다이렉트나 외부 페이지 주입 문제가 됩니다.
**iOS · DeepLinkRouter.swift**
```swift
final class DeepLinkRouter: NSObject, AdbrixDeferredDeepLinkDelegate {
static let shared = DeepLinkRouter()
private let appScheme = "yourapp"
private let webBaseURL = URL(string: "https://your-brand.com")!
weak var webView: WKWebView?
func didReceive(deferredDeepLink: AdbrixDeepLink) {
guard let deepLink = deferredDeepLink.deepLink else { return }
load(deepLink)
}
func load(_ raw: String) {
guard let target = resolve(raw) else { return }
DispatchQueue.main.async { [weak self] in
self?.webView?.load(URLRequest(url: target))
}
}
private func resolve(_ raw: String) -> URL? {
if raw.contains("/api/v1/click/") { return nil }
if let url = URL(string: raw),
url.scheme == appScheme {
return webURL(path: url.path, query: url.query)
}
if raw.hasPrefix("/") {
return URL(string: raw, relativeTo: webBaseURL)?.absoluteURL
}
return nil
}
private func webURL(path: String, query: String?) -> URL? {
var components = URLComponents(url: webBaseURL, resolvingAgainstBaseURL: false)
components?.path = path.isEmpty ? "/" : path
components?.query = query
return components?.url
}
}
```
**Android · DeepLinkRouter.kt**
```kotlin
object DeepLinkRouter {
private const val APP_SCHEME = "yourapp"
private const val WEB_ORIGIN = "https://your-brand.com"
var webView: WebView? = null
fun load(raw: String) {
val target = resolve(raw) ?: return
webView?.post {
webView?.loadUrl(target)
}
}
private fun resolve(raw: String): String? {
if (raw.contains("/api/v1/click/")) return null
val uri = Uri.parse(raw)
if (uri.scheme == APP_SCHEME) {
val path = uri.encodedPath?.ifBlank { "/" } ?: "/"
val query = uri.encodedQuery?.let { "?$it" } ?: ""
return "$WEB_ORIGIN$path$query"
}
if (raw.startsWith("/")) {
return "$WEB_ORIGIN$raw"
}
return null
}
}
```
라우터를 연결하는 위치는 SDK의 딥링크 콜백입니다. iOS는 `AdbrixDeferredDeepLinkDelegate`, Android는 Deferred Deep Link listener에서 받은 값을 위 라우터로 넘깁니다.
**Android · callback 연결**
```kotlin
AdBrixRm.setOnDeferredDeeplinkListener { result ->
val deepLink = result.deeplink ?: return@setOnDeferredDeeplinkListener
DeepLinkRouter.load(deepLink)
}
```
## 6단계. Deferred Deep Link 콜백 처리
Deferred Deep Link는 앱이 설치되어 있지 않은 사용자가 트래킹 링크를 클릭하고 스토어에서 설치한 뒤 첫 실행했을 때, 원래 이동해야 했던 화면 정보를 앱으로 전달하는 흐름입니다. 즉시 딥링크와 달리 “설치 후 첫 실행” 구간까지 검증해야 합니다.
**iOS · Deferred Deep Link delegate**
```swift
class AppDelegate: UIResponder, UIApplicationDelegate, AdbrixDeferredDeepLinkDelegate {
func application(_ application: UIApplication,
didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
Adbrix.shared().setDeferredDeepLinkDelegate(self)
return true
}
func didReceive(deferredDeepLink: AdbrixDeepLink) {
if let deepLink = deferredDeepLink.deepLink,
let url = URL(string: deepLink) {
DeepLinkRouter.shared.load(url.absoluteString)
}
}
}
```
**Android · Deferred Deep Link listener**
```kotlin
AdBrixRm.setOnDeferredDeeplinkListener { result ->
val deeplink = result.deeplink
Log.d("abxrm", "Deferred Deeplink : $deeplink")
DeepLinkRouter.load(deeplink)
}
```
> **팁**
>
> Deferred Deep Link 검증은 기존 설치 앱에서 단순 클릭만 해서는 부족합니다. 테스트 기기에서 앱 삭제 → 트래킹 링크 클릭 → 스토어 또는 테스트 배포 경로로 설치 → 첫 실행 → SDK 콜백 수신 순서로 확인합니다.
## 참고 링크
- [AdBrix 공식 개발자 가이드](https://adbrix.gitbook.io/developer-guide/)
- [AdBrix iOS 연동 가이드](https://adbrix.gitbook.io/developer-guide/platform/ios/integration)
- [AdBrix Android 연동 가이드](https://adbrix.gitbook.io/developer-guide/platform/android/integration)
- [AdBrix 셀프 딥링크 테스트](https://adbrix.gitbook.io/developer-guide/common/deep-link-test)
- [AdBrix 헬프센터](https://help.adbrix.io/hc/ko)
- [Apple Associated Domains 문서](https://developer.apple.com/documentation/xcode/supporting-associated-domains)
- [Android App Links 검증 문서](https://developer.android.com/training/app-links/verify-android-applinks)
- [Google Digital Asset Links 검증기](https://developers.google.com/digital-asset-links/tools/generator)
## 자주 묻는 질문
### Universal Link와 App Link만 적용하면 URI Scheme은 빼도 되나요?
권장하지 않습니다. Universal/App Link는 앱·브라우저 환경에 따라 동작이 달라질 수 있으므로 URI Scheme을 기본으로 두고 Universal/App Link를 보조로 적용하는 편이 안전합니다.
### AASA나 assetlinks.json은 항상 우리가 호스팅해야 하나요?
아닙니다. 고객사 자체 도메인으로 앱 링크를 열 때만 고객사 서버 호스팅이 필요합니다. AdBrix 콘솔의 ABX 도메인이나 대표 도메인을 쓰는 경우에는 콘솔 도메인 설정과 앱 설정 값을 맞추는 쪽이 핵심입니다.
### Deferred Deep Link는 기존 설치 앱 클릭으로 검증할 수 있나요?
아니요. 미설치 상태에서 트래킹 링크 클릭, 설치, 첫 실행까지 이어지는 흐름을 봐야 합니다. 기존 설치 앱에서는 일반 딥링크 검증만 됩니다.
## Navigation
- [전체 플레이북 Markdown sitemap](/wiki/playbook/sitemap.md)
### AdBrix
- [AdBrix](/wiki/playbook/adbrix)
- [AdBrix SDK 초기화](/wiki/playbook/adbrix/how-to-initialize-adbrix-sdk)
- [AdBrix 딥링크 설정](/wiki/playbook/adbrix/how-to-set-up-adbrix-deeplinks) (현재 문서)
- [AdBrix WebView 이벤트 연동](/wiki/playbook/adbrix/how-to-connect-adbrix-webview-events)
- [AdBrix 이벤트 전송](/wiki/playbook/adbrix/how-to-send-adbrix-events)
- [AdBrix 연동 검증](/wiki/playbook/adbrix/how-to-verify-adbrix-integration)