adjust-icon

Android SDK 연동 가이드

Adjust Android SDK를 사용하면 Android 앱에서의 어트리뷰션, 이벤트 등을 기록할 수 있습니다. 본 가이드의 단계를 수행하여 Adjust SDK와 연동되도록 앱을 설정하시기 바랍니다.

1. Adjust SDK 설치

Android 앱에서 Adjust SDK를 사용하려면 우선 프로젝트에 Adjust SDK를 추가해야 합니다. GitHub releases 페이지에서 최신 버전을 다운로드합니다.

Maven을 사용하는 경우, build.gradle 파일에 다음을 추가합니다.

build.gradle
dependencies {
implementation 'com.adjust.sdk:adjust-android:4.38.5'
implementation 'com.android.installreferrer:installreferrer:2.2'
// Add the following if you're using the Adjust SDK inside web views on your app
implementation 'com.adjust.sdk:adjust-android-webbridge:4.38.5'
}

2. Google 플레이 서비스 추가

Google 플레이 스토어를 타겟으로 하는 앱은 기기 식별을 위해 gps_adid(Google 광고 ID)를 사용해야 합니다. gps_adid에 액세스하기 위해 프로젝트에 play-services-ads-identifier AAR을 추가합니다.

Maven을 사용하는 경우, build.gradle 파일에 다음을 추가합니다.

build.gradle
dependencies {
implementation 'com.google.android.gms:play-services-ads-identifier:18.0.1'
}

App Set ID 수집

앱 세트 ID 는 사용자가 기기에 설치한 앱 정보를 측정할 수 있도록 해주는 고유한 ID입니다. 동일한 개발자의 모든 앱은 앱 세트 ID를 공유하기 때문에, 모든 앱 사용자로부터 유의미한 인사이트를 수집할 수 있습니다. 디바이스의 앱 세트 ID를 기록하려면 다음의 권한을 build.gradle 파일에 추가해야 합니다.

build.gradle
dependencies {
implementation 'com.google.android.gms:play-services-appset:16.0.2'
}

이 권한이 활성화되면 App Set ID가 기기 정보 페이로드의 일부로 Adjust 서버로 전송됩니다.

3. 권한 추가

Adjust SDK에 기기 정보에 대한 액세스 권한을 부여하려면 앱에서 요구하는 권한을 선언해야 합니다. 이를 위해 AndroidManifest.xml 파일에 권한을 추가합니다.

온라인 기능에 액세스하려면 다음 권한을 추가하시기 바랍니다.

AndroidManifest.xml
<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>

앱이 Google 플레이 스토어를 타겟으로 하지 않는 경우 기기의 네트워크 상태에 액세스하는 다음 권한을 추가합니다.

AndroidManifest.xml
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>

Adjust SDK에는 com.google.android.gms.AD_ID 권한이 기본값으로 포함됩니다. 앱이 COPPA(Children’s Online Privacy Protection Act, 어린이 온라인 개인정보 보호법) 준수 대상이거나 Google 플레이 스토어를 타겟으로하지 않는 경우 remove를 사용하여 이 권한을 삭제해야 합니다.

AndroidManifest.xml
<uses-permission android:name="com.google.android.gms.permission.AD_ID" tools:node="remove"/>

4. Proguard 설정

앱 최적화를 위해 Proguard를 사용하는 경우 Proguard가 클래스를 삭제하는 것을 방지하는 규칙을 추가해야 합니다.

Proguard.pro
-keep class com.adjust.sdk.** { *; }
-keep class com.google.android.gms.common.ConnectionResult {
int SUCCESS;
}
-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.** { *; }

Google 플레이 스토어에서 앱을 게시하지 않는 경우 다음의 규칙을 추가합니다.

Proguard.pro
-keep public class com.adjust.sdk.** { *; }

5. 설치 리퍼러 설정

설치 리퍼러는 설치를 소스에 어트리뷰션하는 데 사용할 수 있는 고유한 식별자입니다. Adjust SDK는 어트리뷰션을 위해 이 정보가 필요합니다. 다음 메서드 중 하나를 사용하여 설치 리퍼러 정보를 조회하시기 바랍니다.

Google Play Referrer API

Google Play 리퍼러 API는 Google 플레이 스토어를 타겟으로 하는 앱에서 사용할 수 있습니다.

Google Play 리퍼러 API를 지원하려면 build.gradle 파일에 다음을 추가합니다.

build.gradle
dependencies {
implementation 'com.android.installreferrer:installreferrer:2.2'
}

Proguard를 사용하는 경우 dependency가 삭제되는 것을 방지하는 규칙을 추가해야 합니다.

Proguard.pro
-keep public class com.android.installreferrer.** { *; }

Huawei 리퍼러 API

Huawei 리퍼러 API는 Huawei 기기를 타겟으로 하는 앱에서 사용할 수 있습니다. Adjust SDK는 Huawei App Gallery v10.4 이상을 사용하는 Huawei 기기에서의 설치를 기록할 수 있습니다. 이 API를 지원하기 위해 필요한 변경 사항은 없습니다.

Xiaomi 리퍼러 플러그인

Xiaomi 리퍼러 플러그인을 사용하면 Xiaomi 기기를 타겟으로 하는 앱의 설치 리퍼러 값을 기록할 수 있습니다. 자세한 설치 방법은 플러그인 문서를 참조하시기 바랍니다.

삼성 리퍼러 플러그인

Samsung 리퍼러 플러그인을 사용하면 Samsung Galaxy 스토어를 타겟으로 하는 앱의 설치 리퍼러 값을 기록할 수 있습니다. 자세한 설치 방법은 플러그인 문서를 참조하시기 바랍니다.

Meta 리퍼러 연동

v4.36.0에서 추가됨

Adjust SDK는 v4.36.0 이상 버전에서 Meta 설치 리퍼러 를 지원합니다. 이 기능을 활성화하려면 다음을 수행하시기 바랍니다.

  1. 앱 대시보드 에서 Meta 앱 ID를 찾습니다. 자세한 정보는 Meta의 앱 대시보드 문서 를 참고하시기 바랍니다.
  2. 앱 ID를 String 인수로 AdjustConfig.setFbAppId 메서드에 전달합니다.

6. Adjust SDK 연동

Adjust SDK를 초기화하려면 다음 정보가 필요합니다.

  • appToken: Your Adjust app token.
  • environment: The environment your app is running in. Set this to AdjustConfig.ENVIRONMENT_SANDBOX to test your app locally.

Adjust SDK를 초기화하는 권장 방식은 글로벌 Android 애플리케이션 클래스에서 수행하는 것입니다. 아직 설정하지 않은 경우 다음 단계에 따라 앱을 설정하시기 바랍니다.

  1. Application을 확장하는 클래스를 생성합니다.
  2. AndroidManifest.xml 파일을 열고 <application> 요소를 찾습니다.
  3. <application> 요소에 android:name 어트리뷰션을 추가하고 애플리케이션 클래스의 이름으로 설정합니다. 예를 들어 Application 클래스 이름이 GlobalApplication인 경우 다음과 같이 설정합니다.
AndroidManifest.xml
<application android:name=".GlobalApplication">
<!-- ... -->
</application>
  1. Application 클래스에서 onCreate 메서드를 찾거나 존재하지 않는 경우 메서드를 추가합니다. 다음 파라미터를 전달하여 Adjust SDK를 초기화합니다.

    • 고객사 전담팀 appToken
    • 앱을 실행할 environment
    • 기록할 LogLevel

Adjust 웹뷰 SDK 연동

앱이 웹뷰를 사용하는 경우 Adjust 웹뷰 SDK를 사용하여 정보를 기록해야 합니다. 먼저 WebView 객체에 대한 레퍼런스를 얻은 후에 다음 단계를 수행합니다.

  1. webView.getSettings().setJavaScriptEnabled(true)를 호출하여 웹뷰에서 자바스크립트를 활성화합니다.
  2. AdjustBridge.registerAndGetInstance(getApplication(), webview)를 호출하여 디폴트 AdjustBridgeInstance를 시작합니다. 이는 Adjust 브릿지를 웹뷰에서 자바스크립트 인터페이스로 등록합니다.
  3. AdjustBridge.setWebView()를 호출하여 새로운WebView를 설정합니다.
  4. AdjustBridge.unregister()를 호출하여 AdjustBridgeInstanceWebView의 등록을 취소합니다.
  5. 전체 설정에 대한 예시는 다음과 같습니다.
  1. HTML로 Adjust 자바스크립트 파일을 가져옵니다.
<script type="text/javascript" src="adjust.js"></script>
<script type="text/javascript" src="adjust_event.js"></script>
<script type="text/javascript" src="adjust_third_party_sharing.js"></script>
<script type="text/javascript" src="adjust_config.js"></script>
  1. 이제 appTokenenvironmentAdjustConfig 클래스로 전달하여 웹뷰에서 Adjust SDK를 초기화할 수 있습니다.
let yourAppToken = "{YourAppToken}";
let environment = AdjustConfig.EnvironmentSandbox;
let adjustConfig = new AdjustConfig(yourAppToken, environment);
adjustConfig.setLogLevel(AdjustConfig.LogLevelVerbose);
Adjust.onCreate(adjustConfig);

7. 세션 기록 구성

세션 정보를 기록하려면 앱 행동 라이프사이클의 여러 단계에서 메서드를 호출해야 합니다. 이러한 단계는 앱이 타겟으로 하는 API 레벨에 따라 달라집니다.

API 레벨 14 이상

API 레벨 14 이상에 대한 세션 기록을 설정하려면 다음을 수행합니다.

  1. 앱의 활동에 Adjust.onResumeAdjust.onPause 호출이 있다면 이를 삭제합니다.
  2. ActivityLifecycleCallbacks 인터페이스를 도입한 비공개 클래스를 추가합니다.
  3. onActivityResumed(Activity activity) 메서드를 수정하고 Adjust.onResume()에 콜을 추가합니다.
  4. onActivityPaused(Activity activity) 메서드를 수정하고 Adjust.onPause()에 콜을 추가합니다.
  5. Adjust SDK 구성 단계에 onCreate() 메서드를 추가합니다.
  6. 생성된 ActivityLifecycleCallbacks 클래스의 인스턴스를 사용하여 registerActivityLifecycleCallbacks를 호출합니다.

API level 9~13

API 레벨 13 이하를 타겟으로 하는 앱에서 세션 기록을 설정하려면 다음 단계를 수행합니다.

  1. 활동의 onResume 메서드에서 Adjust.onResume()에 콜을 추가합니다.
  2. 활동의 onPause 메서드에서 Adjust.onPause()에 콜을 추가합니다.
  3. 앱에서 각 액티비티에 대해 위 단계를 반복합니다. 코딩 스타일에 따라, 모든 액티비티에 대해 공통 슈퍼클래스에서 본 단계를 추가할 수도 있습니다.

8. 프로덕션을 위한 앱 빌드

테스트를 완료한 후에 프로덕션을 위한 앱을 빌드할 수 있습니다. 이를 위해 config 객체를 업데이트해야 합니다.

  1. 필요한 항목만 반환하도록 로그 수준을 조정합니다.
  2. environmentAdjustConfig.ENVIRONMENT_PRODUCTION로 설정합니다.