菜单

集成文档（Android）

集成神策分析 SDK

引入插件

在 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'
    }
}

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

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

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

引入 SDK

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'
}
  • 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
  1. 如果不需要集成 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 可视化模块  
  2. 若使用 Android 插件 4.0.0+，并且使用了 exclude 排除某些模块，或者是通过 aar 方式集成部分模块，对于 exclude 的模块和未添加的模块，要配置 disableModules 进行排除，具体参考：插件 disableModules  配置。

离线 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 曝光模块 可选

初始化神策分析 SDK

获取项目数据接收地址

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

初始化 SDK 

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

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

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

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

权限配置说明

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

配置 Scheme

获取项目 Scheme

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

App 中添加 Scheme

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

5.2.2 及以上的 SDK

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

5.2.2 以下的 SDK

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

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

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

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

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

SDK 基本配置

开启全埋点

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

用户关联

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

设置事件公共属性

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

记录激活事件

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

代码埋点追踪事件

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

调试查看事件信息

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

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

在 Logcat 中筛选 SA. 关键词：

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

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

SDK 可选配置

打通 App 与 H5

版本要求

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

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

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

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
}

可视化全埋点

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

上一个
Android SDK
下一个
基础 API 介绍（Android）
最近修改: 2024-12-30