# 연동하기 이 문서는 Adbrix Android SDK를 Android에 통합하는 방법을 다룹니다. Adbrix SDK를 설치하면 이벤트 분석 기능이 제공됩니다. 더 자세히 알아보려면 [리소스 및 샘플](https://adbrix.gitbook.io/developer-guide/common/resource-and-sample)을 참조하세요. ## 시작하기 전에 ### 앱 생성 [Adbrix 콘솔](https://console.adbrix.ai/)의 `앱 설정/앱 정보` 페이지에서 앱을 생성하여 SDK 초기화에 필요한 **Application Key**와 **Secret Key**를 발급받아 주십시오. ![앱 정보](https://3478783164-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnJIV3KSW5duLCA7m693B%2Fuploads%2Fgit-blob-6228fd98bac706c18facda8b3b9116f69ff3f57d%2Fappinfo.png?alt=media) ### 지원 정보 * 최소 지원 SDK : Android 4.4+ / API 19+ * 컴파일된 SDK : 35 ## SDK 설치 ### 의존성 추가하기 앱에서 Adbrix SDK의 의존성을 적용하려면 다음 단계를 완료하세요. #### 1. maven 의존성을 가져오기 위해 repositories 내에 `mavenCentral`을 추가합니다. {% tabs %} {% tab title="build.gradle (Gradle 3.5 이전)" %} ```groovy allprojects { repositories { mavenCentral() } } ``` {% endtab %} {% tab title="settings.gradle (Gradle 3.5 이후)" %} ```groovy pluginManagement { repositories { mavenCentral() } } dependencyResolutionManagement { repositories { mavenCentral() } } ``` {% endtab %} {% endtabs %} #### 2. 앱의 모듈 디렉터리 내에 있는 `build.gradle` 파일을 엽니다. #### 3. dependencies에 [최신 버전의 Adbrix SDK](https://github.com/IGAWorksDev/adbrix-android-sdk/releases)와 필요한 요소에 대해 SDK 종속 항목을 추가합니다. {% tabs %} {% tab title="build.gradle" %} ```groovy dependencies { //Get the latest version from https://mvnrepository.com/artifact/com.igaworks.adbrix/android-sdk implementation 'com.igaworks.adbrix:android-sdk:HERE_LATEST_VERSION' implementation 'com.android.installreferrer:installreferrer:2.2' implementation 'com.google.android.gms:play-services-ads-identifier:18.0.1' } ``` {% endtab %} {% tab title="build.gradle.kts" %} ```groovy dependencies { //Get the latest version from https://mvnrepository.com/artifact/com.igaworks.adbrix/android-sdk implementation("com.igaworks.adbrix:android-sdk:HERE_LATEST_VERSION") implementation("com.android.installreferrer:installreferrer:2.2") implementation("com.google.android.gms:play-services-ads-identifier:18.0.1") } ``` {% endtab %} {% endtabs %} ## SDK 초기화 ### 초기화 하기 앱에서 Adbrix SDK를 초기화하려면 다음 단계를 완료하세요. #### 1. Application을 상속한 객체를 생성합니다. 상속한 객체가 이미 있을 경우 해당 객체를 사용합니다. {% tabs %} {% tab title="Java" %} ```java public class BaseApplication extends Application ``` {% endtab %} {% tab title="Kotlin" %} ```kotlin class BaseApplication: Application() ``` {% endtab %} {% endtabs %} #### 2. Application을 상속한 객체에서 [onCreate()](https://developer.android.com/reference/android/app/Application#onCreate\(\)) 메소드를 Override 합니다. {% tabs %} {% tab title="Java" %} ```java @Override public void onCreate() { super.onCreate(); } ``` {% endtab %} {% tab title="Kotlin" %} ```kotlin override fun onCreate() { super.onCreate() } ``` {% endtab %} {% endtabs %} #### 3. onCreate() 메소드 내에 다음 코드를 작성합니다. {% hint style="info" %} Application KEY와 SECRET KEY는 [Adbrix Console](https://console.adbrix.ai/)의 `앱 설정 > 앱 정보`에서 확인이 가능합니다. {% endhint %} {% tabs %} {% tab title="Java" %} ```java Adbrix.getInstance().init(this, "{YOUR_APPLICATION_KEY}", "{YOUR_SECRET_KEY}"); ``` {% endtab %} {% tab title="Kotlin" %} ```kotlin Adbrix.getInstance().init(this, "{YOUR_APPLICATION_KEY}", "{YOUR_SECRET_KEY}") ``` {% endtab %} {% endtabs %} 다음 코드 스니펫은 초기화 작성 완료 시의 예를 보여줍니다. {% tabs %} {% tab title="Java" %} ```java public class BaseApplication extends Application{ @Override public void onCreate() { super.onCreate(); Adbrix.getInstance().init(this, "{YOUR_APPLICATION_KEY}", "{YOUR_SECRET_KEY}"); } } ``` {% endtab %} {% tab title="Kotlin" %} ```kotlin class BaseApplication: Application(){ override fun onCreate() { super.onCreate() Adbrix.getInstance().init(this, "{YOUR_APPLICATION_KEY}", "{YOUR_SECRET_KEY}") } } ``` {% endtab %} {% endtabs %} #### 4. AndroidManifest.xml에 작성한 Application을 등록합니다. ```xml ``` #### 5. AndroidManifest.xml에 필요한 권한을 추가합니다. ```xml ``` #### 6. Proguard 설정 앱 최적화를 위해 Proguard를 사용하는 경우 Proguard가 클래스를 삭제하는 것을 방지하는 규칙을 추가해야 합니다. ``` -keep class com.igaworks.adbrix.** { *; } -keep class com.google.android.gms.ads.identifier.AdvertisingIdClient { com.google.android.gms.ads.identifier.AdvertisingIdClient$Info getAdvertisingIdInfo(android.content.Context); } -keep class com.google.android.gms.ads.identifier.AdvertisingIdClient$Info { java.lang.String getId(); boolean isLimitAdTrackingEnabled(); } -keep public class com.android.installreferrer.** { *; } ``` #### 7. 완료 되었습니다. ### 구글 광고 ID 설정하기 Google 광고 ID를 수집하기 위해선 init시에 `setCollectGoogleAdvertisingId(boolean isCollect)` Config를 통해 수집 여부를 설정해야합니다. 만약 Google 광고ID를 수집하지 않아야 한다면, [구글 광고 ID 수집 여부 변경하기](#change_collect_google_advertising_id)를 통해 수집하지 않도록 설정할 수 있습니다. #### 1. AndroidManifest.xml에 필요한 권한을 추가합니다. ```xml ``` #### 2. AdbrixConfig의 `setCollectGoogleAdvertisingId(boolean isCollect)` 메소드를 통해 광고 ID의 수집 여부를 변경합니다. {% tabs %} {% tab title="Java" %} ```java AdbrixConfig config = new AdbrixConfig.Builder() .setCollectGoogleAdvertisingId(true) .build(); Adbrix.getInstance().init(this, "{YOUR_APPLICATION_KEY}", "{YOUR_SECRET_KEY}", config); ``` {% endtab %} {% tab title="Kotlin" %} ```kotlin val config = AdbrixConfig.Builder() .setCollectGoogleAdvertisingId(true) .build() Adbrix.getInstance().init(this, "{YOUR_APPLICATION_KEY}", "{YOUR_SECRET_KEY}", config) ``` {% endtab %} {% endtabs %} #### 5. 완료 되었습니다. ## 딥링크 오픈 분석 딥링크 정보를 가지고 있는 트래킹링크를 클릭하면 딥링크에 설정된 [Activity](https://developer.android.com/reference/android/app/Activity)가 실행됩니다. 딥링크가 정보가 없을 경우 `android.intent.action.MAIN` 액션을 가지고 있는 Activity가 실행됩니다. {% hint style="info" %} Activity에 딥링크를 연동하는 방법은 Android에서 제공하는 [앱 콘텐츠 딥링크 만들기](https://developer.android.com/training/app-links/deep-linking?hl=ko)를 참고하여 주시기 바랍니다. {% endhint %} ### 딥링크 연동하기 #### Activity에 인텐트 적용 딥링크 추적을 위해 딥링크로 인해 실행 될 Activity에 `setIntent()`를 추가해주시기 바랍니다. {% hint style="warning" %} Activity가 이미 실행 중일 때(launchMode가 singleTop/singleTask인 경우) 새로운 딥링크를 수신하려면 onNewIntent에서 인텐트를 갱신해줘야 합니다. {% endhint %} {% tabs %} {% tab title="Java" %} ```java @Override protected void onNewIntent(Intent intent) { super.onNewIntent(intent); // 전달받은 새로운 인텐트로 교체해야 SDK가 정상적으로 데이터를 추출합니다. setIntent(intent); } ``` {% endtab %} {% tab title="Kotlin" %} ```kotlin override fun onNewIntent(intent: Intent?) { super.onNewIntent(intent) // 전달받은 새로운 인텐트로 교체해야 SDK가 정상적으로 데이터를 추출합니다. setIntent(intent) } ``` {% endtab %} {% endtabs %} #### AndroidManifest 적용 개발자는 앱에서 사용할 **스킴(Scheme)** 과 **호스트(Host)** 를 결정하여 `AndroidManifest.xml`에 등록해야 합니다. 딥링크로 인해 실행 될 Activity에 다음 내용의 ``를 추가합니다. **android:scheme** > 콘솔에서 `성과측정 > 성과측정 설정 > 광고 랜딩 설정`에서 설정한 **딥링크 스킴**과 동일해야합니다. 앱을 식별하는 고유 주소입니다. 보통 서비스 명칭을 사용합니다. * 예: `adbrix` **android:host** > 콘솔에서 `성과 측정 > 트래킹 링크 > 딥링크 패스 방식`에서 트래킹 링크를 생성할 때 **딥링크 패스(Path)** 항목에 입력할 값과 동일해야 합니다. 앱 내 특정 페이지를 구분하는 값입니다. **AndroidManifest.xml 설정 예시** 이 경우 딥링크 주소는 `adbrix://main`이 됨 ```xml ``` ### 앱링크 연동하기(선택사항) Android App Links를 적용하면 딥링크 클릭 시 '연결 프로그램' 선택창 없이 앱이 즉시 실행됩니다. 이를 위해 트래킹 서버와 앱 간의 소유권 확인(Verification) 과정이 필요합니다. **커스텀 도메인 설정** `성과측정 > 성과측정 설정 > 도메인 설정`에서 커스텀(브랜드, ABX) 도메인으로 대표 도메인 설정을 합니다. {% hint style="warning" %} 트래킹 링크 원본 도메인은 앱링크로 사용할 수 없습니다. 커스텀 도메인이 없다면 새 도메인을 생성해주세요. {% endhint %} #### SHA256 Cert Fingerprints 등록 `성과측정 > 성과측정 설정 > 광고 랜딩 설정`에서 SHA256 Cert Fingerprints를 등록합니다. **SHA256 지문 추출 방법** 앱링크(App Links)의 보안 검증을 위해, 앱을 서명한 인증서의 고유 지문(SHA256)이 필요합니다. 상황에 맞는 방법을 선택하여 추출하세요. **방법 1: Google Play 콘솔에서 확인 (가장 권장)** 앱이 구글 플레이 스토어에 등록되어 있고 'Google Play 앱 서명'을 사용 중이라면, 이 값이 실제 배포본의 최종 지문입니다. 1. [Google Play Console](https://play.google.com/console/)에 로그인합니다. 2. 출시할 앱을 선택한 뒤, **설정 > 앱 서명** 메뉴로 이동합니다. 3. **앱 서명 인증서** 항목에 있는 **SHA-256 인증서 지문**을 복사합니다. **방법 2: Android Studio의 Gradle 테스크 이용** 개발 환경에서 빠르게 확인하고 싶을 때 유용합니다. 1. Android Studio 우측 상단의 **Gradle** 탭을 클릭합니다. 2. `[프로젝트명] > Tasks > android > signingReport`를 찾아 더블 클릭합니다. 3. 하단 **Run** 창에 출력되는 결과에서 사용 중인 빌드 변형(Variant)의 **SHA256** 값을 확인합니다. **방법 3: 터미널에서 keytool 명령어 사용** 로컬에 저장된 키스토어(`.jks` 또는 `.keystore`) 파일에서 직접 추출합니다. 1. 터미널(또는 CMD)을 열고 아래 명령어를 입력합니다. ```bash keytool -list -v -keystore [키스토어_파일_경로] -alias [별칭] ``` 2. 키스토어 비밀번호를 입력하면 출력되는 정보 중 `SHA256:` 뒤의 문자열을 복사합니다. {% hint style="warning" %} * **디버그와 릴리즈 구분:** 개발 시 사용하는 `debug.keystore`와 마켓 배포용 릴리즈 키의 지문은 서로 다릅니다. 실제 광고 라이브 시에는 반드시 **배포용(Release)** 지문을 등록해야 합니다. * **포맷 확인:** 지문은 `AA:BB:CC...`와 같이 16진수 쌍으로 구성됩니다. 콘솔 등록 시 대소문자나 콜론(`:`) 포함 여부를 가이드에 맞게 확인해 주세요. {% endhint %} #### AndroidManifest 적용 앱링크로 인해 실행 될 Activity에 ``를 추가합니다. * `android:scheme` : 앱링크를 사용하기 위해 **https** 를 적용합니다. * `android:autoVerify` : 앱 설치 시 구글 시스템이 서버의 `assetlinks.json`을 확인하도록 반드시 **true** 로 적용합니다. * `android:host` : 발급받은 트래킹 링크의 도메인(Host)을 입력합니다. * `android:pathPrefix` : 도메인 이후부터 Application Key가 포함된 경로까지만 정확히 입력합니다. 그 뒤의 트래킹 ID나 파라미터는 포함하지 않습니다. **트래킹 링크 예시** ```http https://click2.igaworks.com/api/v1/click/mHZYsiYiSUmjIWN1Llt46A/HLJENPSt0kSSdXpj78RErg?abx_tracker_id=HLJENPSt0kSSdXpj78RErg ``` * Host: `click2.igaworks.com` * Application Key: `mHZYsiYiSUmjIWN1Llt46A` * 필요한 pathPrefix: `/api/v1/click/mHZYsiYiSUmjIWN1Llt46A` **AndroidManifest.xml 설정 예시** ```xml ``` ### 트래킹 링크 생성 설정한 scheme와 host 정보를 토대로 `성과 측정 > 트래킹 링크 > 트래킹 링크 생성`에서 트래킹 링크를 생성합니다. {% hint style="info" %} 트래킹 링크 생성 방법은 사용자 가이드의 [트래킹 링크](https://adbrix.gitbook.io/user-guide/undefined-2/publish-your-docs) 가이드를 참고해주시기 바랍니다. {% endhint %} | 구분 | 개발자 설정 항목 (Manifest) | 마케터 입력 항목 (Console) | 예시 | | ------- | -------------------- | ------------------- | -------- | | **스킴** | `android:scheme` | 딥링크 스킴 | `adbrix` | | **호스트** | `android:host` | 딥링크 패스 (Path) | `main` | {% hint style="success" %} **연동 확인 절차** 1. 개발자가 `adbrix://main`을 앱에 등록 후 배포. 2. 마케터가 콘솔에서 패스를 `main`으로 지정하여 트래킹 링크 생성. 3. 해당 트래킹 링크 클릭 시 앱의 `main` 호스트를 가진 Activity가 실행됨. {% endhint %} ### 지연된 딥링크 핸들링하기(선택사항) SDK는 앱이 설치되지 않은 유저가 트래킹 링크를 클릭 후 앱을 설치했을때 자동으로 딥링크를 실행합니다. 직접 지연된 딥링크를 핸들링 하려면 다음 메소드를 호출하여 자동 딥링크 실행을 막을 수 있습니다. ```java blockDeferredDeepLinkLaunch(AdbrixDeferredDeepLinkListener listener): void ``` {% hint style="warning" %} 해당 메소드를 호출할 경우 지연된 딥링크의 경로로 Activity를 실행하지 않으므로 필요할 경우 직접 이동시켜야합니다. {% endhint %} {% tabs %} {% tab title="Java" %} ```java Adbrix.getInstance().blockDeferredDeepLinkLaunch(new AdbrixDeferredDeepLinkListener() { @Override public void onDeferredDeepLinkReceived(Context context, AdbrixDeepLink adbrixDeepLink){ String deepLink = adbrixDeepLink.getDeepLink(); } }); ``` {% endtab %} {% tab title="Kotlin" %} ```kotlin Adbrix.getInstance().blockDeferredDeepLinkLaunch { context, adbrixDeepLink -> val deepLink: String = adbrixDeepLink.deepLink } ``` {% endtab %} {% endtabs %} #### AdbrixDeepLink **result: ABDeepLinkResult** 지연된 딥링크 처리 결과 입니다. ABDeepLinkResult 클래스로 해당 결과 값의 의미를 파악할수있습니다. ```java adbrixDeepLink.getResult() ``` * 결과 값 의미 * 0 : `PROCESSED` * 1 : `ORGANIC` * 2 : `TRACKING_LINK_SETTINGS_INCORRECTLY` * 3 : `ORGANIC_NCPI_IN_PROCESS` * -1 : `NO_CONVERSION` **deepLink : String** 지연된 딥링크 값입니다. ```java adbrixDeepLink.getDeepLink() ``` ## SDK 설정 SDK 초기화 시에 로그 활성화 등의 옵션을 설정할 수 있습니다. ### 로그 활성화 하기 로그 활성화는 Adbrix의 설정을 적용하는 AdbrixConfig를 사용하여 설정 가능합니다. AdbrixConfig는 `init()` 메소드 호출 시에 파라미터로 넣어 적용할 수 있습니다. ```java setLogEnable(boolean enable) ``` * 첫 번째 인자인 `enable`은 로그를 표시할지 말지 설정하는 값입니다. 기본값은 `false`입니다. {% hint style="success" %} `BuildConfig.DEBUG` 값을 넣어 디버그 모드일때만 로그가 출력 되고 배포시에는 출력되지 않게끔 설정할 수 있습니다. {% endhint %} {% tabs %} {% tab title="Java" %} ```java AdbrixConfig config = new AdbrixConfig.Builder() .setLogEnable(true) .build(); Adbrix.getInstance().init(this, "{YOUR_APPLICATION_KEY}", "{YOUR_SECRET_KEY}", config); ``` {% endtab %} {% tab title="Kotlin" %} ```kotlin val config = AdbrixConfig.Builder() .setLogEnable(true) .build() Adbrix.getInstance().init(this, "{YOUR_APPLICATION_KEY}", "{YOUR_SECRET_KEY}", config) ``` {% endtab %} {% endtabs %} ### 로그 레벨 변경하기 로그 레벨은 Adbrix의 설정을 적용하는 AdbrixyConfig를 사용하여 설정 가능합니다. AdbrixConfig는 `init()` 메소드 호출 시에 파라미터로 넣어 적용할 수 있습니다. {% hint style="info" %} 로그 레벨 값은 [`android.util.Log`](https://developer.android.com/reference/android/util/Log#constants_1)의 상수 값의 정의를 따릅니다. {% endhint %} ```java setLogLevel(int logLevel) ``` * 첫번째 인자인 `logLevel`은 로그 표시 레벨을 설정하는 값입니다. 기본값은 `Log.ERROR(6)` 입니다. {% tabs %} {% tab title="Java" %} ```java AdbrixConfig config = new AdbrixConfig.Builder() .setLogLevel(Log.DEBUG) .build(); Adbrix.getInstance().init(this, "{YOUR_APPLICATION_KEY}", "{YOUR_SECRET_KEY}", config); ``` {% endtab %} {% tab title="Kotlin" %} ```kotlin val config = AdbrixConfig.Builder() .setLogLevel(Log.DEBUG) .build() Adbrix.getInstance().init(this, "{YOUR_APPLICATION_KEY}", "{YOUR_SECRET_KEY}", config) ``` {% endtab %} {% endtabs %} ### 구글 광고 ID 수집 여부 변경하기 Adbrix의 설정을 적용하는 AdbrixyConfig를 사용하여 구글 광고 ID의 수집 여부를 변경할 수 있습니다. AdbrixConfig는 `init()` 메소드 호출 시에 파라미터로 넣어 적용할 수 있습니다. ```java setCollectGoogleAdvertisingId(boolean isCollect) ``` * 기본값은 `false` 입니다. {% tabs %} {% tab title="Java" %} ```java AdbrixConfig config = new AdbrixConfig.Builder() .setCollectGoogleAdvertisingId(true) .build(); Adbrix.getInstance().init(this, "{YOUR_APPLICATION_KEY}", "{YOUR_SECRET_KEY}", config); ``` {% endtab %} {% tab title="Kotlin" %} ```kotlin val config = AdbrixConfig.Builder() .setCollectGoogleAdvertisingId(true) .build() Adbrix.getInstance().init(this, "{YOUR_APPLICATION_KEY}", "{YOUR_SECRET_KEY}", config) ``` {% endtab %} {% endtabs %} ## 완료 SDK 설치 및 초기화가 완료되었습니다.