在使用前，请先阅读数据模型
SDK 的更新日志，可参阅 Release Notes
插件的更新日志，可参阅 Release Notes

1. 集成神策分析 SDK

1.1. 引入插件

在 project 级别的 build.gradle 文件中添加 android-gradle-plugin2 依赖：

buildscript {
    repositories {
		mavenCentral()
        jcenter()
    }
    dependencies {
		// 添加 gradle 3.2.0+ 依赖
        classpath 'com.android.tools.build:gradle:3.5.3'
        // 添加神策分析 android-gradle-plugin2 依赖
        classpath 'com.sensorsdata.analytics.android:android-gradle-plugin2:4.0.3'
    }
}

GROOVY

在主 module 的 build.gradle 文件中应用 com.sensorsdata.analytics.android 插件依赖：

apply plugin: 'com.android.application'
// 应用 com.sensorsdata.analytics.android 插件
apply plugin: 'com.sensorsdata.analytics.android'

dependencies {
}

GROOVY

关于如何在 AGP 8.0+ 版本中使用插件以及插件的常用配置，请参考 SDK 插件说明。
Android Plugin 需要 Android Gradle Plugin 3.2.0+，否则会导致元素点击事件和 Fragment 的页面浏览事件无法触发，App 和 H5 打通功能受影响。

插件与 SDK 版本依赖关系：

插件版本	可用 SDK 版本范围
v4.0.1 <= 插件版本	v6.6.9 <= SDK 版本
v3.5.2 <= 插件版本 <= 3.5.4	v6.5.3 <= SDK 版本 <= v6.6.8
v3.5.0 <= 插件版本 <= 3.5.1	v6.5.0 <= SDK 版本 <= v6.5.2
v3.4.0 <= 插件版本 <= 3.4.9	v5.4.3 <= SDK 版本 <= v6.4.4
v3.3.9 == 插件版本	v5.4.2 == SDK 版本
v3.3.4 <= 插件版本 <= v3.3.8	v5.1.0 <= SDK 版本 <= v5.4.1
v3.2.12 <= 插件版本 <= v3.3.3	v4.3.2 <= SDK 版本 <= v5.4.1
v3.2.4 <= 插件版本 <= v3.2.11	v4.0.7 <= SDK 版本 <= v5.4.1
v3.0.0 <= 插件版本 <= v3.2.1	v3.0.4 <= SDK 版本 <= v5.4.1

1.2. 引入 SDK

1.2.1. Maven 依赖集成

在主 module 的 build.gradle 文件中添加 SDK 依赖：

apply plugin: 'com.android.application'
// 应用 com.sensorsdata.analytics.android 插件
apply plugin: 'com.sensorsdata.analytics.android'

dependencies {
   // 添加 Sensors Analytics SDK 依赖
   implementation 'com.sensorsdata.analytics.android:SensorsAnalyticsSDK:6.8.3'
}

GROOVY

Android SDK 要求最低系统版本为 API 14（Android 4.0）
目前，Android SDK ( aar 格式) 大小约为 800 KB

推荐版本

推荐版本	版本链接
最新版	https://github.com/sensorsdata/sa-sdk-android/releases
v6.2.8	https://github.com/sensorsdata/sa-sdk-android/releases/tag/v6.2.8
v5.4.4	https://github.com/sensorsdata/sa-sdk-android/releases/tag/v5.4.4
v5.0.2	https://github.com/sensorsdata/sa-sdk-android/releases/tag/v5.0.2
v4.0.9	https://github.com/sensorsdata/sa-sdk-android/releases/tag/v4.0.9

如果不需要集成 SDK 中的所有功能，可以单独排除某些模块，比如排除全埋点模块：
implementation ('com.sensorsdata.analytics.android:SensorsAnalyticsSDK:6.8.0') {
exclude(group:'com.sensorsdata.analytics.android', module:'autoTrack')
}
SDK 子模块名称列表：

名称	模块名	说明
core	核心模块
advert	广告模块
autoTrack	全埋点模块	忽略模块时，对于使用 v4.0.0 及以上的插件需要配置插件忽略全埋点模块插码。 `sensorsAnalytics { disableModules = ['AUTOTRACK'] }`
encrypt	加密模块
exposure	曝光模块
push	推送模块	忽略模块时，对于使用 v4.0.0 及以上的插件需要配置插件忽略推送模块插码。 `sensorsAnalytics { disableModules = ['PUSH'] }`
visual	可视化模块

若使用 Android 插件 4.0.0+，并且使用了 exclude 排除某些模块，或者是通过 aar 方式集成部分模块，对于 exclude 的模块和未添加的模块，要配置 disableModules 进行排除，具体参考：插件 disableModules 配置。

1.2.2. 离线 aar 包集成

离线 aar 包的形式支持按需集成，请您根据自身业务需求到 SDK Releases 中下载并引用相关的 SDK。

AAR 名称	功能描述	是否必选
sa_core.aar	基础模块，包含基础的代码埋点	必选
sa_autoTrack.aar	全埋点模块	可选
sa_visua.aar	可视化热图模块	可选
sa_push.aar	推送模块	可选
sa_encrypt.aar	加密模块	可选
sa_adver.aar	广告渠道模块	可选
sa_exposure.aar	曝光模块	可选

2. 初始化神策分析 SDK

2.1. 获取项目数据接收地址

每个项目都有单独的数据接收地址
请使用 管理员 账户获取相应项目的数据接收地址

2.2. 初始化 SDK

在 Application 的 onCreate() 方法中同步调用 SensorsDataAPI.startWithConfigOptions() 初始化 SDK：

String SA_SERVER_URL = "数据接收地址";

// 初始化配置
SAConfigOptions saConfigOptions = new SAConfigOptions(SA_SERVER_URL);
// 需要在主线程初始化神策 SDK
SensorsDataAPI.startWithConfigOptions(this, saConfigOptions);

CODE

延迟初始化 SDK 会导致全埋点采集不准确和可视化全埋点、点击分析功能异常，若 App 有合规需求，可参考 Android 合规步骤。

2.2.1. 权限配置说明

SDK 共需要四个权限：

权限	用途	备注
INTERNET	必须权限，允许应用发送统计数据，SDK 发送埋点数据需要此权限
ACCESS_NETWORK_STATE	必须权限，允许应用检测网络状态，SDK 会根据网络状态选择是否发送数据
READ_PHONE_STATE	可选权限，允许应用获取设备 IMEI，采用 App 内推广和采集 $carrier 属性时会用到此权限	Android v6.8.0 及以上版本神策 SDK只用来 Android11 及以上系统版本获取网络类型
ACCESS_WIFI_STATE	可选权限，允许应用获取 MAC 地址，采用 App 内推广时会用到此权限	Android v6.8.0 及以上版本神策 SDK 无需授权开通此权限，已删除该权限声明

SDK 为简化集成步骤，默认在 AndroidManifest.xml 中注册了以上四个权限。如果想要去除 SDK 注册的权限，可以使用 tools:node="remove" 配置。关于 tools:node="remove" 的详细说明可参考谷歌官方文档，配置代码参考：

<uses-permission android:name="android.permission.READ_PHONE_STATE" tools:node="remove" />

CODE

3. 配置 Scheme

3.1. 获取项目 Scheme

项目的 Scheme 需要管理员账户进行获取
App 工程中可以同时配置多个项目的 Scheme

3.2. App 中添加 Scheme

在使用神策系统中的 Debug 实时查看、App 点击分析、可视化全埋点等需要扫码的功能时，需要给某一个 Activity 配置 scheme，配置后扫码即可拉起该 Activity 页面并且与神策系统建立连接使用相关功能。

在 AndroidManifest 文件中，配置以下 Activity，并将 scheme 的值替换为您项目中的值

<!-- Android 12 需添加 android:exported="true"-->
<activity android:name="com.sensorsdata.analytics.android.sdk.dialog.SchemeActivity"
	android:configChanges="orientation|screenSize"
	android:exported="true"
	android:launchMode="singleTask">
    <intent-filter>
          <action android:name="android.intent.action.VIEW" />
          <category android:name="android.intent.category.BROWSABLE" />
          <category android:name="android.intent.category.DEFAULT" />
          <data android:scheme="您项目的 scheme" />
    </intent-filter>
</activity>

XML

获取 scheme 后，在 AndroidManifest 文件中的 Activity 标签内配置 scheme，以 MainActivity 为例：

<activity android:name=".MainActivity">
<!-- 在 MainActivity 中配置 Scheme-->
	<intent-filter>
		<action android:name="android.intent.action.VIEW" />
		<category android:name="android.intent.category.BROWSABLE" />
		<category android:name="android.intent.category.DEFAULT" />
		<data
			android:scheme="您项目的 Scheme 值" />
	</intent-filter>
</activity>

XML

配置 scheme 时，intent-filter 需要单独配置，不要和其他 intent-filter 混用。scheme 不能配置在含有 <action android:name="android.intent.action.MAIN" /> 的 intent-filter 中，会导致应用无法打开。

4. SDK 基本配置

4.1. 开启全埋点

全埋点详细使用文档参见基础 API 功能介绍。

4.2. 用户关联

用户关联是为了对用户进行唯一标识，提高用户行为分析的准确性。目前神策提供了简易用户关联和全域用户关联分为用于支撑不同的业务场景。

4.3. 设置事件公共属性

对于所有事件都需要添加的属性，初始化 SDK 后，可以通过 registerSuperProperties() 将属性注册为公共属性。详细使用文档参见基础 API 功能介绍。

4.4. 记录激活事件

可以调用 trackAppInstall() 方法记录激活事件，多次调用此方法只会在第一次调用时触发激活事件。详细使用文档参见渠道追踪与广告。

4.5. 代码埋点追踪事件

完成 SDK 初始化后，可以通过 track() 方法追踪用户行为事件，并为事件添加自定义属性。详细使用文档参见基础 API 功能介绍。

5. 调试查看事件信息

初始化 SDK 时，进行以下配置，即可打开 SDK 的日志输出功能：

// 打开 SDK 的日志输出功能
saConfigOptions.enableLog(true);

JAVA

在 Logcat 中筛选 SA. 关键词：

埋点事件触发成功时，SDK 会输出 track event 开头的事件数据
埋点事件触发失败时，SDK 会输出相应的错误原因，常见的有出现 JSON 异常
事件数据上报成功时，SDK 会输出 valid message 字段开头的事件数据
事件数据上报失败时，SDK 会输出 invalid message 字段开头的事件数据并输出错误原因

或通过 SensorsDataAPI.sharedInstance().enableLog(boolean) 接口随时控制日志功能的开启或关闭。

6. SDK 可选配置

6.1. 打通 App 与 H5

版本要求

Android SDK v4.0.8 及以上版本
Android 插件 v3.2.4 及以上版本

初始化 SDK 时，进行如下配置，即可开启 App 打通 H5 功能。

// 开启 App 打通 H5
saConfigOptions.enableJavaScriptBridge(boolean isSupportJellyBean);

CODE

isSupportJellyBean：是否支持 API level 16 及以下的版本。打通功能通过 WebView 的 addJavascriptInterface() 方法实现，但在 API level 16 及以下的版本，addJavascriptInterface() 方法有安全漏洞，因此请谨慎使用。

打通功能需要 App 和 H5 同时开启才可以生效，H5 开启方法请参考 App 打通 H5。

X5 内核打通，在初始化后添加 SensorsDataAPI.sharedInstance().showUpX5WebView(WebView,true);

UC 内核的 WebView 除了调用上述 showUpX5WebView 代码外，还需要在插件配置中添加：addUCJavaScriptInterface = true 这个选项，在主 module 级别的 build.gradle 文件中添加我们的扩展如下；

sensorsAnalytics{
	addUCJavaScriptInterface=true
}

CODE

6.2. 可视化全埋点

在 SDK 初始化时调用 enableVisualizedProperties 开启可视化全埋点，详细使用文档参照基础 API 功能中的可视化全埋点介绍。