欢迎使用神策分析 Android SDK!

新书推荐《Android 全埋点解决方案》


1. 集成神策分析 SDK

1.1. 引入插件

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

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

1.2. 引入 SDK

在主 module 的 build.gradle 文件中应用 com.sensorsdata.analytics.android 插件、添加 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:4.1.1'
}
GROOVY
  • Android SDK 要求最低系统版本为 API 9(Android 2.3)
  • 目前,Android SDK ( aar 格式) 大小约为 300 KB
  • Android SDK 在 AndroidManifest.xml 中注册了可能使用到的权限,具体的权限和用途可参考权限配置说明

2. 初始化神策分析 SDK

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

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

2.2. 初始化 SDK 

在 Application 的 onCreate() 方法中主线程调用 SensorsDataAPI.startWithConfigOptions() 初始化 SDK:

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

// 初始化配置
SAConfigOptions saConfigOptions = new SAConfigOptions(SA_SERVER_URL);
// 开启全埋点
saConfigOptions.setAutoTrackEventType(SensorsAnalyticsAutoTrackEventType.APP_CLICK |
                SensorsAnalyticsAutoTrackEventType.APP_START |     
                SensorsAnalyticsAutoTrackEventType.APP_END |       
                SensorsAnalyticsAutoTrackEventType.APP_VIEW_SCREEN)
				//开启 Log
				.enableLog(true);
/**
 * 其他配置,如开启可视化全埋点
 */
// 需要在主线程初始化神策 SDK
SensorsDataAPI.startWithConfigOptions(this, saConfigOptions);
JAVA

3. 配置 Scheme

3.1. 获取项目 Scheme

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

3.2. App 中添加 Scheme

获取 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. 开启全埋点

初始化 SDK 时,setAutoTrackEventType() 方法可以配置需要开启的全埋点类型。全埋点其他配置,可参考全埋点 (Android)

4.2. 设置事件公共属性

对于所有事件都需要添加的属性,初始化 SDK 后,可以通过 registerSuperProperties() 将属性注册为公共属性。设置方法如下:

// 将应用名称作为事件公共属性,后续所有 track() 追踪的事件都会自动带上 "AppName" 属性
try {
    JSONObject properties = new JSONObject();
    properties.put("AppName", getAppName(this));
    SensorsDataAPI.sharedInstance().registerSuperProperties(properties);
} catch (JSONException e) {
    e.printStackTrace();
}
JAVA

公共属性会保存在 App 本地缓存中。可以通过 unregisterSuperProperty() 删除一个公共属性,或使用 clearSuperProperties() 删除所有已设置的事件公共属性。

4.3. 用户登录

当用户注册成功或登录成功时,需要调用 SDK 的 login() 方法:

SensorsDataAPI.sharedInstance().login("登录 ID");
JAVA

为了准确记录登录用户的行为信息,建议在以下时机各调用一次 login() 方法:

· 用户在注册成功时
· 用户登录成功时
· 已登录用户每次启动 App 时

4.4. 记录激活事件

可以调用 trackInstallation() 方法记录激活事件,多次调用此方法只会在第一次调用时触发激活事件:

if(Build.VERSION.SDK_INT >=Build.VERSION_CODES.M){
    if (ActivityCompat.checkSelfPermission(this, "android.permission.READ_PHONE_STATE") != PackageManager.PERMISSION_GRANTED) {
        // 6.0 以上,无权限时,先申请 READ_PHONE_STATE 权限。
        ActivityCompat.requestPermissions(this, new String[]{"android.permission.READ_PHONE_STATE"}, 100);
    } else {
        // 6.0 以上,有权限时,直接触发激活事件。
        trackInstallation();
    }
} else {
    // 6.0 以下,无须申请权限,直接触发激活事件。
    trackInstallation();
}
JAVA

在权限回调的 onRequestPermissionsResult() 方法中,申请权限结果回调无论申请权限成功失败,都要调用 trackInstallation()

@Override
public void onRequestPermissionsResult(int requestCode, @NonNull String[] permissions, @NonNull int[] grantResults) {
    super.onRequestPermissionsResult(requestCode, permissions, grantResults);
    if (requestCode == 100) {
        // 申请权限结果回调时(无论申请权限成功失败),都需要触发激活事件。
        trackInstallation();
    }
}


/**
 * 记录激活事件
 */
private void trackInstallation() {
    try {
        JSONObject properties = new JSONObject();
		//这里的 DownloadChannel 负责记录下载商店的渠道,值应传入具体应用商店包的标记。如果没有为不同商店打多渠道包,则可以忽略该属性的代码示例。
        properties.put("DownloadChannel", "XXX");
        // 触发激活事件
        SensorsDataAPI.sharedInstance().trackInstallation("AppInstall", properties);
    } catch (Exception e) {
        e.printStackTrace();
    }
}
JAVA

更多关于渠道追踪功能的说明,请参考渠道追踪

4.5. 代码埋点追踪事件

SDK 初始化后,可以通过 track() 方法追踪用户行为事件,并为事件添加自定义属性:

try {
    JSONObject properties = new JSONObject();
    properties.put("ProductID", 123456);                    // 设置商品 ID
    properties.put("ProductCatalog", "Laptop Computer");    // 设置商品类别
    SensorsDataAPI.sharedInstance().track("BuyProduct", properties);
} catch (JSONException e) {
    e.printStackTrace();
}
JAVA

事件名和事件属性的格式规范,请参考数据格式

5. 调试查看事件信息

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

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

Logcat 中筛选 SA. 关键词:

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

6. SDK 可选配置

6.1. 设置用户属性

profileSet() 方法可以设置用户属性,同一个 key 被多次设置时,value 的值会进行覆盖替换:

try {
    JSONObject properties = new JSONObject();
    // 设定用户性别属性 "Sex" 为 "Male"
    properties.put("Sex", "Male");
    // 设定用户年龄属性 "Age" 为 18
    properties.put("Age", 18);

    // 设定用户属性
    SensorsDataAPI.sharedInstance().profileSet(properties);
} catch (JSONException e) {
    e.printStackTrace();
}
JAVA


6.2. 打通 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 及以下的版本。打通功能通过 WebViewaddJavascriptInterface() 方法实现,但在 API level 16 及以下的版本,addJavascriptInterface()  方法有安全漏洞,因此请谨慎使用。

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

6.3. 可视化全埋点

版本要求

  • 神策分析 v1.17.2517+
  • Android SDK v4.0.0+

SDK 初始化时,进行如下配置,即可开启可视化全埋点:

// 开启可视化全埋点
saConfigOptions.enableVisualizedAutoTrack(true);
JAVA