安卓 SDK 集成指南

通过 Adjust 安卓 SDK，您可以在安卓应用中记录归因、事件及更多数据。请按照本指南中说明的步骤操作，在应用内设置 Adjust SDK。

操作前须知

在更新到 SDK v5 之前，您需要进行以下操作：

1. SDK v5 支持SDK 签名验证。如果您当前正在使用 SDK 签名库，则需要先将其卸载。
2. 如果您的应用针对的是低于21的 API 版本，则需要先更新应用才能使用 SDK v5。

1. 设置环境

要开始使用 Adjust SDK，您首先要将其作为 dependency 添加至项目中。Adjust SDK 可在Maven上使用。

要将 Adjust SDK 添加至您的项目：

1. 将 Beta 库添加至您的build.gradle文件：

   repositories {
      maven {
         url "https://oss.sonatype.org/content/repositories/snapshots/"
      }
   }

2. 将 Adjust SDK和安卓 Install Referrer 实现添加至您的 build.gradle 文件。如果您在应用中使用网页视图，则可以选择添加 Adjust web view bridge。

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

2. 添加 Google Play 服务

定向到 Google Play 商店的应用必须使用gps_adid(Google 广告 ID) 来识别设备。要访问 gps_adid，请向项目中添加 play-services-ads-identifier AAR。

如果您使用的是 Maven，请将以下行添加至您的 build.gradle 文件：

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

3. 添加权限

要授予 Adjust SDK 读取设备信息的权限，您需要声明您应用所需的权限。为此，请在 AndroidManifest.xml 文件中添加权限。

请添加下列许可，以访问在线功能：

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

如果您的应用并不面向 Google Play 商店，那么请添加下列权限，以读取设备的互联网连接状态：

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

Adjust SDK 默认包含 com.google.android.gms.AD_ID 权限。如果您要让应用符合 COPPA (儿童在线隐私保护法) 规定，或者应用并不面向 Google Play 商店，请务必使用 remove 命令移除权限。

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

4. 设置 Proguard

如果您使用 Proguard 优化应用，那么请务必添加规则，避免Proguard 移除类：

-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 Play 商店发布，请添加下列规则：

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

5. 设置 Install Referrer

Install Referrer 是一种唯一标识符，可用来将安装归因至来源。Adjust SDK 需要该信息进行归因。您可以使用下列方法之一调取 install referrer 信息：

Google Play Referrer API

面向 Google Play 商店的应用可以使用 Google Play Referrer API。

要支持 Google Play Referrer API，请将下列行添加进您的 build.gradle 文件：

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

如果您使用的是 Proguard，请务必添加规则，避免依赖被移除。

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

华为 Referrer API

面向华为设备的应用可以使用华为 Referrer API。Adjust SDK 可以使用 Adjust Huawei Referrer 插件记录华为设备上的安装。

要安装插件，请将下列依赖添加至您的build.gradle文件：

dependencies {
   implementation: "com.adjust.sdk:adjust-android-huawei-referrer:5.0.0-beta1"
}

小米 referrer 插件

借助小米 referrer 插件，您可以记录面向小米设备应用的 Install Referrer 值。请查看插件相关文档，了解安装信息。

Samsung referrer 插件

借助 Samsung referrer 插件，您可以记录面向 Samsung Galaxy Store 的应用的 Install Referrer 值。请查看插件相关文档，了解安装信息。

Meta referrer 集成

通过 Adjust Meta Install Referrer 插件，Adjust SDK 可以支持Meta Install Referrer。请参阅文档了解集成详情。

6. 集成 Adjust SDK

初始化 Adjust SDK 必需信息如下：

• appToken：Adjust 应用识别码。
• environment：应用运行的环境。要在本地测试应用，请设置为 AdjustConfig.ENVIRONMENT_SANDBOX。

我们建议您在全局 Android Application 类中初始化 Adjust SDK。如果您还没有为自己的应用完成该设置，请按照下列步骤进行设置：

1. 创建一个扩展 Application的类。

2. 打开 AndroidManifest.xml 文件，找到 <application> 元素。

3. 添加 android:name 属性至 <application> 元素，并将其设置为 Application 类的名称。例如，如果您的 Application 类名称为 GlobalApplication，那么您可以进行如下设置：

   <application android:name=".GlobalApplication">
      <!-- ... -->
   </application>

4. 在 Application 类中找到 initSdk 方法；如果方法不存在，请进行添加。传送下列参数，以初始化 Adjust SDK：

   • 您的 appToken
   • 应用运行预期 environment
   • 要记录的 LogLevel

集成 Adjust Web View SDK

如果您的应用使用的是 web 视图，请通过 Adjust Web View SDK 记录信息。您需要获得对 WebView 对象的引用。完成后，请按照下列步骤操作：

1. 调用 webView.getSettings().setJavaScriptEnabled(true) 在 web view 中启用 Javascript。
2. 调用 AdjustBridge.registerAndGetInstance(getApplication(), webview)，启动默认 AdjustBridgeInstance。这会将 Adjust bridge 注册为 web view 的 Javascript 接口。
3. 调用 AdjustBridge.setWebView()，已设置新的 WebView。
4. 调用 AdjustBridge.unregister() 来注销 AdjustBridgeInstance 和 WebView 。
5. 完整设置示例如下：

6. 在 HTML 中导入 Adjust Javascript 文件：

   <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>

7. 现在，您可以将 appToken 和 environment 传送至 AdjustConfig 类，以在 web 视图中初始化 Adjust SDK：

   let yourAppToken = "{YourAppToken}";
   let environment = AdjustConfig.EnvironmentSandbox;
   let adjustConfig = new AdjustConfig(yourAppToken, environment);
   adjustConfig.setLogLevel(AdjustConfig.LogLevelVerbose);
   Adjust.initSdk(adjustConfig);

7. 针对生产环境构建应用

完成测试后，您就可以针对生产环境构建应用了。为此，请更新您的 config 对象。

1. 调整日志等级，仅返回您需要的信息。
2. 将您的 environment 设为 AdjustConfig.ENVIRONMENT_PRODUCTION。

通过 Adjust 安卓 SDK，您可以在安卓应用中记录归因、事件及更多数据。请按照本指南中说明的步骤操作，在应用内设置 Adjust SDK。

1. 获取 Adjust SDK

要在您的 Android 应用中使用 Adjust SDK，请先将 SDK 加入项目。您可以从GitHub 发布页面下载最新版本的 SDK。

如果您使用的是 Maven，请将以下行添加至您的 build.gradle 文件：

dependencies {
   implementation 'com.adjust.sdk:adjust-android:v4.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:v4.38.5'
}

2. 添加 Google Play 服务

定向到 Google Play 商店的应用必须使用 gps_adid (Google 广告 ID) 来识别设备。要访问 play-services-ads-identifier，请向项目中添加 gps_adid AAR。

如果您使用的是 Maven，请将以下行添加至您的 build.gradle 文件：

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

收集 App Set Identifier

App Set Identifier 是一个唯一标识符，用户在设备上安装您的应用后，您可以通过此标识符监测这些应用的信息。同一位开发者开发的所有应用共享同一个 App Set ID，也就是说您可以从所有应用中收集有用的洞见。要记录设备的 App Set ID，您需要向build.gradle 文件中添加下列权限：

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

如果启用该权限，那么 App Set ID 就会作为设备信息负载的一部分被发送到 Adjust 服务器。

3. 添加权限

要授予 Adjust SDK 读取设备信息的权限，您需要声明您应用所需的权限。为此，请在 AndroidManifest.xml 文件中添加权限。

请添加下列许可，以访问在线功能：

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

如果您的应用并不面向 Google Play 商店，那么请添加下列权限，以读取设备的互联网连接状态：

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

Adjust SDK 默认包含 com.google.android.gms.AD_ID 权限。如果您要让应用符合 COPPA (儿童在线隐私保护法) 规定，或者应用并不面向 Google Play 商店，请务必使用 remove 命令移除权限。

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

4. 设置 Proguard

如果您使用 Proguard 优化应用，那么请务必添加规则，避免Proguard 移除类：

-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 Play 商店发布，请添加下列规则：

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

5. 设置 Install Referrer

Install Referrer 是一种唯一标识符，可用来将安装归因至来源。Adjust SDK 需要该信息进行归因。您可以使用下列方法之一调取 install referrer 信息：

Google Play Referrer API

面向 Google Play 商店的应用可以使用 Google Play Referrer API。

要支持 Google Play Referrer API，请将下列行添加进您的 build.gradle 文件：

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

如果您使用的是 Proguard，请务必添加规则，避免依赖被移除。

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

华为 Referrer API

面向华为设备的应用可以使用华为 Referrer API。Adjust SDK 可以针对装有华为 App Gallery v10.4 或更新版本的华为设备记录安装信息。您无需进行任何调整，即可开始使用该 API。

小米 referrer 插件

借助小米 referrer 插件，您可以记录面向小米设备应用的 Install Referrer 值。请查看插件相关文档，了解安装信息。

Samsung referrer 插件

借助 Samsung referrer 插件，您可以记录面向 Samsung Galaxy Store 的应用的 Install Referrer 值。请查看插件相关文档，了解安装信息。

Meta referrer 集成

Adjust SDK v4.36.0 及更高版本支持Meta Install Referrer。要启用该功能：

1. 在应用控制面板中找到您的 Meta app ID。更多信息，请参考 Meta 的应用控制面板文档。
2. 将应用 ID 作为 String 参数传递至 AdjustConfig.setFbAppId 方法。

6. 集成 Adjust SDK

初始化 Adjust SDK 必需信息如下：

• appToken：Adjust 应用识别码。
• environment：应用运行的环境。要在本地测试应用，请设置为 AdjustConfig.ENVIRONMENT_SANDBOX。

我们建议您在全局 Android Application 类中初始化 Adjust SDK。如果您还没有为自己的应用完成该设置，请按照下列步骤进行设置：

1. 创建一个扩展 Application的类。
2. 打开 AndroidManifest.xml 文件，找到 <application> 元素。
3. 添加 android:name 属性至 <application> 元素，并将其设置为 Application 类的名称。例如，如果您的 Application 类名称为 GlobalApplication，那么您可以进行如下设置：

<application android:name=".GlobalApplication">
   <!-- ... -->
</application>

4. 在 Application 类中找到 onCreate 方法；如果方法不存在，请进行添加。传送下列参数，以初始化 Adjust SDK：

   • 您的 appToken
   • 应用运行预期 environment
   • 要记录的 LogLevel

集成 Adjust Web View SDK

如果您的应用使用的是 web 视图，请通过 Adjust Web View SDK 记录信息。您需要获得对 WebView 对象的引用。完成后，请按照下列步骤操作：

1. 调用 webView.getSettings().setJavaScriptEnabled(true) 在 web view 中启用 Javascript。
2. 调用 AdjustBridge.registerAndGetInstance(getApplication(), webview)，启动默认 AdjustBridgeInstance。这会将 Adjust bridge 注册为 web view 的 Javascript 接口。
3. 调用 AdjustBridge.setWebView()，已设置新的 WebView。
4. 调用 AdjustBridge.unregister() 来注销 AdjustBridgeInstance 和 WebView 。
5. 完整设置示例如下：

6. 在 HTML 中导入 Adjust Javascript 文件：

<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>

7. 现在，您可以将 appToken 和 environment 传送至 AdjustConfig 类，以在 web 视图中初始化 Adjust SDK：

let yourAppToken = "{YourAppToken}";
let environment = AdjustConfig.EnvironmentSandbox;
let adjustConfig = new AdjustConfig(yourAppToken, environment);
adjustConfig.setLogLevel(AdjustConfig.LogLevelVerbose);
Adjust.onCreate(adjustConfig);

7. 配置会话记录

要记录会话信息，您需要在应用活动生命周期的多个不同阶段调用多种方法。根据应用定向的 API level，这些阶段会有不同。

API level 14 及更高

要为定向 API level 14 或更高级别的应用设置会话记录，请按照下列步骤操作：

1. 如果您的活动中有 Adjust.onResume 和 Adjust.onPause，请将其移除。
2. 添加一个私有类 (private class) ，以部署 ActivityLifecycleCallbacks 接口。
3. 编辑 onActivityResumed(Activity activity) 方法，添加 Adjust.onResume()调用。
4. 编辑 onActivityPaused(Activity activity) 方法，添加 Adjust.onPause()调用。
5. 将 onCreate() 方法添加至您的 Adjust SDK 配置步骤。
6. 使用已创建 ActivityLifecycleCallbacks 类的实例调用 registerActivityLifecycleCallbacks：

API level 9 至 13

要为定向 API level 13 或更低级别的应用设置会话记录，请按照下列步骤操作：

1. 向活动的 onResume 方法添加 Adjust.onResume() 调用。
2. 向活动的 onPause 方法添加 Adjust.onPause() 调用。
3. 对您的应用中的每个 Activity 重复以上步骤。取决于编码方式，您也可通过添加所有 Activitiy 的通用超类来实现它。

7. 针对生产环境构建应用

完成测试后，您就可以针对生产环境构建应用了。为此，请更新您的 config 对象。

1. 调整日志等级，仅返回您需要的信息。
2. 将您的 environment 设为 AdjustConfig.ENVIRONMENT_PRODUCTION。