Android SDK 使用说明

最后更新于:2019-07-12 16:44:24

在使用前,请先阅读数据模型的介绍。

更新日志

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

1. 集成神策分析 SDK

在 Android App 中集成 神策分析 SDK 采集数据,之后便可以通过神策分析来分析用户行为。

Gradle 编译环境(Android Studio)

第一步:project 级别的 build.gradle 文件中添加 Sensors Analytics android-gradle-plugin 依赖:

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

allprojects {
    repositories {
        jcenter()
    }
}

如下示例图:

第二步:主 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:3.2.0'
}

SensorsAnalyticsSDK 的最新版本号请参考 GitHub 更新日志

如下示例图:

Android SDK 要求最低系统版本为 API 9(Android 2.3)。AutoTrack 功能要求系统最低版本为 API 14 (Android 4.0)如果 API 低于14 开启 AutoTrack 后 将不能采集 $AppStart、$AppViewScreen、$AppEnd 事件。目前,Android SDK (aar格式) 大小约为 350 KB。

第三步: 关于 SDK 权限说明

SDK 共需要四个权限

权限 用途
INTERNET 允许应用发送统计数据
ACCESS_NETWORK_STATE 允许应用检测网络状态
READ_PHONE_STATE 允许应用获取设备 IMEI
ACCESS_WIFI_STATE 允许应用获取 MAC 地址

各个权限详细说明:

  • INTERNET
    • 必须权限,SDK 发送埋点数据需要此权限
  • ACCESS_NETWORK_STATE
    • 必须权限,SDK 会根据网络状态选择是否发送数据
  • READ_PHONE_STATE
    • 可选权限,采用 App 内推广和采集 $carrier 属性时会用到此权限
  • ACCESS_WIFI_STATE

如何删除在 AmdridManifest.xml 中已注册权限?

神策 SDK 为简化开发者集成步骤,默认在 AmdridManifest.xml 中注册了以上四个权限,如果开发者不需要其中某个权限,可以使用 tools:node="remove" 属性删除,打包后的 AmdridManifest.xml 文件将不再包含此权限,关于 tools:node="remove" 的详细说明可参考谷歌官方文档,配置参考代码如下:

如果不是特殊要求,可不配置此代码

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

注意: 如果使用了 MultiDex ,请确保神策 Android SDK 的代码都指定到主 DEX 中。可以通过在 multiDexKeepProguard 里添加如下配置:

-keep class com.sensorsdata.analytics.android.** { *; }

2. 初始化神策分析 SDK

2.1 获取配置信息

首先从神策分析系统中,获取数据接收和配置分发的 URL。

如果使用神策分析 Cloud 服务,需获取的配置信息为:

如果用户使用单机版私有部署的神策分析,默认的配置信息为:

如果用户使用集群版私有部署的神策分析,默认的配置信息为:

其中 {$host_name} 可以是集群中任意一台机器。

如果私有部署的过程中修改了 Nginx 的默认配置,或通过 CDN 等访问神策分析,则请咨询相关人员获得配置信息。

2.2 在 App 中使用

在程序的入口 ApplicationonCreate() 中调用 SensorsDataAPI.sharedInstance(),并且在主线程中初始化 SDK:

// 引入神策分析 SDK
import com.sensorsdata.analytics.android.sdk.SensorsDataAPI;
import com.sensorsdata.analytics.android.sdk.SAConfigOptions;


// 数据接收的 URL
final String SA_SERVER_URL = "YOUR_SERVER_URL";

//需要在主线程初始化 SDK
SensorsDataAPI.sharedInstance(this,new SAConfigOptions(SA_SERVER_URL));
  • 3.0.4 及之前的版本,SDK 初始化方式:

请注意:Debug 模式是为方便开发者调试而设置的模式,该模式会逐条校验数据并在校验失败时抛出异常,性能远低于正常模式。线上环境使用 Debug 模式会严重影响性能并存在崩溃风险,产品上线前请务必替换掉/关闭 Debug 模式。

其中 YOUR_SERVER_URL 是前文中从神策分析获取的数据接收的 URL。一旦成功初始化后,则可以通过 sharedInstance 获取 SDK 实例,进行用户行为事件或属性的追踪。

注意:利用 SAConfigOptions 设置全埋点类型、开启 crash 采集时等操作时,只有 SDK 第一次初始化时有效。请勿对多个 SAConfigOptions 对象进行相关设置

至此,我们已经可以正常使用神策分析 SDK 了。需了解更多关于 SDK 的配置方法,可以跳到本文末尾的 控制神策分析 SDK 一节。

3. 追踪事件

第一次接入神策分析时,建议先追踪 3~5 个关键的事件,只需要几行代码,便能体验神策分析的分析功能。例如:

  • 图片社交产品,可以追踪用户浏览图片和评论事件
  • 电商产品,可以追踪用户浏览商品和下订单等事件

神策分析 SDK 成功初始化后,可以通过 track() 方法追踪用户行为事件,并为事件添加自定义属性。以电商产品为例,可以这样追踪一次购物行为:

// 在用户浏览商品页面时...

try {
    JSONObject properties = new JSONObject();
    properties.put("ProductID", 123456);                    // 设置商品ID
    properties.put("ProductCatalog", "Laptop Computer");    // 设置商品类别
    properties.put("IsAddedToFav", false);                  // 是否被添加到收藏夹

    SensorsDataAPI.sharedInstance().track("ViewProduct", properties);
} catch (JSONException e) {
    e.printStackTrace();
}

// 在用户结账付款时...

try {
    JSONArray orderList = new JSONArray();
    orderList.put("Apple iPhone6s");
    orderList.put("Nexus 6");

    JSONObject properties = new JSONObject();
    properties.put("OrderPaid", 50.10);                     // 订单支付金额
    properties.put("OrderList", orderList);                 // 产品列表
    properties.put("OrderDate", new Date());                // 订单时间
    SensorsDataAPI.sharedInstance().track("PaidOrder", properties);
} catch (JSONException e) {
    e.printStackTrace();
}

触发事件后,在神策分析中稍等片刻,便能看到追踪结果。

3.1 Auto Track

SDK 可以自动采集一些用户行为,如 App 启动、退出、浏览页面、控件点击等。可以通过 SAConfigOptions 对象打开自动采集:

SAConfigOptions saConfigOptions = new SAConfigOptions(SA_SERVER_URL);
//在初始化时,利用 SAConfigOptions 对象开启全埋点
saConfigOptions.setAutoTrackEventType(SensorsAnalyticsAutoTrackEventType.APP_CLICK|
        SensorsAnalyticsAutoTrackEventType.APP_START|
        SensorsAnalyticsAutoTrackEventType.APP_END|
        SensorsAnalyticsAutoTrackEventType.APP_VIEW_SCREEN);

SensorsDataAPI.sharedInstance(this, saConfigOptions);
  • 3.1.0 及之前的版本,SDK 开启全埋点方式:

打开 Auto Track 后,采集的事件包括:

  • 点击控件时,会发送 $AppClick 事件,包含点击的相应控件的基本信息。
    • $element_id - String 类型,为元素 ID,例如为 android:id 属性设置的值
    • $element_type - String 类型,为元素类型,比如 Button、CheckBox 等
    • $element_content - String 类型,为元素内容,比如是 Button、TextView 显示的文本
    • $screen_name - String 类型,表示 Activity 的包名.类名
    • $title - String 类型,表示 Activity 的标题
  • App 启动且符合 session 机制时,会自动记录 $AppStart 事件,事件属性:
    • $is_first_time - boolean 类型,true 表示 App 安装后首次启动,false 则相反
    • $resume_from_background - boolean 类型,true 表示 App 从后台恢复,false 表示 App 启动
    • $screen_name - String 类型,表示 Activity 的包名.类名
    • $title - String 类型,表示 Activity 的标题
  • App 进入后台且符合 session 机制时,会自动记录 $AppEnd 事件,事件属性:
    • event_duration - long 类型,表示本次 App 启动的使用时长,单位为秒
    • $screen_name - String 类型,表示 Activity 的包名.类名
    • $title - String 类型,表示 Activity 的标题
  • App 浏览页面时(切换 Activity),会自动记录记录 $AppViewScreen 事件,事件属性:
    • $title - String 类型,表示 Activity 的标题(1.6.31 及以后版本支持该属性)。Android SDK 按照如下逻辑读取 title 属性:首先读取 activity.getTitle(),如果使用 actionBar,并且 actionBar.getTitle() 不为空,则actionBar.getTitle() 覆盖 activity.getTitle(),如果以上两步都没有读到 title,则获取 activityandroid:label 属性。
    • $screen_name - String 类型,表示 Activity 的包名.类名

关于 AutoTrack 的更详细文档,请参考

3.2 记录激活事件

可以调用 trackInstallation 方法记录激活事件,多次调用此方法只会触发一次激活事件。触发激活事件时会尝试获取 IMEI 号,请动态申请 android.permission.READ_PHONE_STATE 权限后再调用 trackInstallation

例如,在 ActivityonCreate 方法中申请权限:

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() 触发激活事件。
        trackInstallation();
        }
} else {
    // 6.0 以下,直接调用 trackInstallation() 触发激活事件。
    trackInstallation();
}

在权限回调的 onRequestPermissionsResult 方法中,调用 trackInstallation

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


/**
 * 记录激活事件
 */
private void trackInstallation() {
    try {
        JSONObject properties = new JSONObject();
        properties.put("DownloadChannel", "XXX");//这里的 DownloadChannel 负责记录下载商店的渠道。这里传入具体应用商店包的标记。
        //记录 AppInstall 激活事件
        SensorsDataAPI.sharedInstance().trackInstallation("AppInstall", properties);
    } catch (Exception e) {
        e.printStackTrace();
    }
}

3.3 事件属性

每个事件可以设置多个事件属性,例如浏览商品事件中,将商品 ID、商品分类等信息作为事件属性。在后续的分析工作中,事件属性可以作为统计过滤条件使用,也可以作为维度进行多维分析。对于事件属性,神策分析有一些约束:

  • 事件属性是一个 JSONObject 对象
  • JSONObject 中每个元素描述一个属性,Key 为属性名称,必需是 String 类型
  • JSONObject 中,每个元素的 Value 是属性的值,支持 StringNumberBooleanJSONArrayDate,对于 JSONArray,其中所有元素必须是 String 类型

3.3.1 SDK 默认属性

神策分析SDK 会自动收集 App 版本、网络状态、IP、设备型号等一系列系统信息作为事件属性,详细的默认属性列表请参考文档 数据格式

3.3.2 事件公共属性

特别地,如果某个事件的属性,在所有事件中都会出现,可以通过 registerSuperProperties() 将该属性设置为事件公共属性。例如添加应用程序名称为事件的公共属性,设置方法如下:

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

成功设置事件公共属性后,再通过 track() 追踪事件时,事件公共属性会被添加进每个事件中,例如:

// 记录收藏商品事件
try {
    JSONObject properties = new JSONObject();
    properties.put("ProductID", 123456);
    SensorsDataAPI.sharedInstance().track("AddToFav", properties);
} catch (JSONException e) {
    e.printStackTrace();
}

在设置事件公共属性后,实际发送的事件中会被加入 AppName 属性,等价于

// 记录收藏商品事件
try {
    JSONObject properties = new JSONObject();
    properties.put("ProductID", 123456);
    properties.put("AppName", getAppName(this));
    SensorsDataAPI.sharedInstance().track("AddToFav", properties);
} catch (JSONException e) {
    e.printStackTrace();
}

重复调用 registerSuperProperties 会覆盖之前已设置的公共属性,公共属性会保存在 App 本地 SharedPreferences 存中。可以通过 unregisterSuperProperty() 删除一个公共属性,使用 clearSuperProperties() 会删除所有已设置的事件公共属性。

当事件公共属性和事件属性的 Key 冲突时,事件属性优先级最高,它会覆盖事件公共属性。

注意:
  1. 请在开启自动采集( enableAutoTrack )之前调用 registerSuperProperties 方法,确保每个事件都会添加已设置的公共属性。

  2. 神策事件属性大小写敏感( 详见 数据格式 ),设置公共属性前需确保事件表中不存在仅大小写不同的同名属性,否则会导致所有事件因存在同名属性而不能入库。

3.4 事件时长

可以通过计时器统计事件的持续时间。首先,在事件开始时调用(1.10.6 及以后版本支持) trackTimerStart("Event") 记录事件开始时间,该方法并不会真正发送事件;在事件结束时,调用 trackTimerEnd("Event", properties),SDK 会追踪 "Event" 事件,并自动将事件持续时间记录在事件属性 "event_duration" 中。

例如记录用户浏览商品页面的时间:

// 进入商品页面
// 调用 trackTimerStart("ViewProduct") 标记事件启动时间
SensorsDataAPI.sharedInstance().trackTimerStart("ViewProduct");

// ... 用户浏览商品

// 离开商品页
try {
  // 在属性中记录商品 ID
  JSONObject properties = new JSONObject();
  properties.put("product_id", PRODUCT_ID);
  // 调用 track,记录 ViewProduct 事件,并在属性 event_duration 中记录用户浏览商品的时间
  SensorsDataAPI.sharedInstance().trackTimerEnd("ViewProduct", properties);
} catch (JSONException e) {
  e.printStackTrace();
}

多次调用 trackTimerStart("Event") 时,事件 "Event" 的开始时间以最后一次调用时为准。

4. 识别用户

在集成了神策分析 SDK 的 App 中,SDK 会为每个设备分配一个匿名 ID(UUID.randomUUID().toString()),用于标记产生事件的未登录用户,并以此进行用户相关分析,如留存率、事件漏斗等。

当用户重新安装 App 或更换设备时,神策分析会重新分配一个匿名 ID。

1.10.5 及以后的版本默认使用 AndroidId 作为 匿名 ID

通过 getAnonymousId 方法 获取神策分析 SDK 分配的 匿名 ID

//获取当前用户的匿名id
String AnonymousId=SensorsDataAPI.sharedInstance().getAnonymousId();

注意: 如果服务端做了埋点,需在用户注册/登录的时候将匿名 ID 传给服务端做用户 ID 关联。

4.1 匿名 ID 和登录 ID 关联

用户在登录前 ,SDK 会分配一个匿名 ID 来标识游客。当用户注册成功或登录成功时调用 login 方法,传入对应的登录 ID ;匿名 ID 会与对应的登录 ID 进行关联,关联成功之后视为同一个用户。

调用时机:注册成功、登录成功 、初始化 SDK(如果能获取到登录 ID)都需要调用 login 方法传入登录 ID。

注意:登录 ID 是指可以唯一标识一个用户的 ID,通常是业务数据库里的主键或其它唯一标识。

//注册成功、登录成功、初始化SDK后  调用 login 传入登录 ID
SensorsDataAPI.sharedInstance().login("你们服务端分配给用户具体的登录 ID");

注意,对同一个用户,login() 可调用多次,多次调用 login() 时,如果新设置的 登录 ID 与之前缓存的 登录 ID 相同,神策分析会忽略该次调用。

5. 设置用户属性

为了更准确地提供针对人群的分析服务,可以使用神策分析 SDK 的 profileSet() 等方法设置用户属性,如年龄、性别等。用户可以在留存分析、分布分析等功能中,使用用户属性作为过滤条件,精确分析特定人群的指标。

使用 profileSet(),可以设定用户属性,例如:

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();
}

使用 profileUnset() 可以删除特定用户的属性值。

用户属性中,属性名称与属性值的约束条件与事件属性相同,详细说明请参考 数据格式

5.1 记录初次设定的属性

对于只在首次设置时有效的属性,我们可以使用 profileSetOnce() 记录这些属性。与 profileSet() 方法不同的是,如果被设置的用户属性已存在,则这条记录会被忽略而不会覆盖已有数据,如果属性不存在则会自动创建。因此,profileSetOnce() 比较适用于为用户设置首次激活时间、首次注册时间等属性。例如:

try {
    JSONObject properties = new JSONObject();
    properties.put("AdSource", "XXX Store");

    // 设定用户渠道为,"developer@sensorsdata.cn" 的 "AdSource" 属性值为 "XXX Store"
    SensorsDataAPI.sharedInstance().profileSetOnce(properties);

    JSONObject newProperties = new JSONObject();
    newProperties.put("AdSource", "Email");

    // 再次设定用户渠道,设定无效,"developer@sensorsdata.cn" 的 "AdSource" 属性值仍然是 "XXX Store"
    SensorsDataAPI.sharedInstance().profileSetOnce(newProperties);
} catch (JSONException e) {
    e.printStackTrace();
}

5.2 数值类型的属性

对于数值型的用户属性,可以使用 profileIncrement() 对属性值进行累加。常用于记录用户付费次数、付费额度、积分等属性。例如:

// 将用户游戏次数属性增加一次
SensorsDataAPI.sharedInstance().profileIncrement("GamePlayed", 1);

// 增加用户付费次数和积分
Map<String, Number> properties = new HashMap<String, Number>();
properties.put("UserPaid", 1);
properties.put("PointEarned", 12.5);

SensorsDataAPI.sharedInstance().profileIncrement(properties);

5.3 列表类型的属性

对于用户喜爱的电影、用户点评过的餐厅等属性,可以记录列表型属性,例如:

Set<String> movies = new HashSet<String>();
movies.add("Sicario");
movies.add("Love Letter");

// 设定用户观影列表属性,设定后属性 "Movies" 为: ["Sicario", "Love Letter"]
SensorsDataAPI.sharedInstance().profileAppend("Movies", movies);

// 再次设定该属性,属性 "Movies" 为: ["Sicario", "Love Letter", "Dead Poets Society"]
SensorsDataAPI.sharedInstance().profileAppend("Movies", "Dead Poets Society");

需要注意的是,列表型属性中的元素必须为 String 类型,且元素的值会自动去重。关于列表型限制请见 数据格式

6. 高级功能

6.1 新增用户与渠道追踪

神策分析 SDK 提供渠道追踪功能,详情介绍请参考 《新增用户与渠道追踪》

6.2 打通 Android App 与 H5

神策分析 SDK 提供打通 iOS App 与 H5 功能,详情介绍请参考 《打通 Android App 与 H5》

6.3 替换默认匿名 ID

如果需要替换神策分析默认分配的 匿名 ID可以通过在初始化 SDK 之后立即调用 identify() 方法进行替换。例如:

// 替换用户匿名ID: '9771C579-71F0-4650-8EE8-8999FA717761'
SensorsDataAPI.sharedInstance().identify("9771C579-71F0-4650-8EE8-8999FA717761");

6.4 添加应用程序名称

神策分析 SDK 默认不采集应用程序的名称,如果想添加该属性,可直接获取应用程序名称,然后以公共属性的形式添加到事件中。具体操作如下:

//初始化SDK后,获取应用名称设置为公共属性
try {
    JSONObject properties=new JSONObject();
    properties.put("AppName",getAppName(this));
    SensorsDataAPI.sharedInstance().registerSuperProperties(properties);
} catch (JSONException e) {
    e.printStackTrace();
}

/**
 * 获取应用程序名称
 */
public static String getAppName(Context context){
    try {
        PackageManager packageManager=context.getPackageManager();
        PackageInfo packageInfo=packageManager.getPackageInfo(context.getPackageName(),0);
        int labelRes = packageInfo.applicationInfo.labelRes;
        return context.getResources().getString(labelRes);
    } catch (PackageManager.NameNotFoundException e) {
        e.printStackTrace();
    }
    return null;
}

注意:请在开启自动采集( enableAutoTrack )之前添加该属性,确保每个事件都会添加已设置的公共属性。

6.5 开启 crash 信息的收集

1.8.12 及以后的版本支持 crash 信息收集, App crash 时,会触发 AppCrashed 事件,堆栈信息记录在 app_crashed_reason 属性中。

SAConfigOptions saConfigOptions = new SAConfigOptions(SA_SERVER_URL);
//利用初始化的 SAConfigOptions 对象开启 crash 信息采集 
saConfigOptions.enableTrackAppCrash();
  • 3.1.0 及之前的版本,开启 crash 采集:

6.6 获取预置属性

1.8.17 及以后的版本可以调用 getPresetProperties方法获取预置属性。 一般用于服务端埋点需要 App 端的一些预置属性时,可以通过此方法获取 App 端的预置属性传给自己的服务端。

//获取预置属性
JSONObject presetProperties=SensorsDataAPI.sharedInstance().getPresetProperties();

6.7 开启屏幕方向属性的采集

1.10.1 及以后的版本可以通过 enableTrackScreenOrientation方法开启屏幕方向属性的收集, 屏幕方向信息记录在事件的 $screen_orientation 属性中。

//开启屏幕方向属性的收集
SensorsDataAPI.sharedInstance().enableTrackScreenOrientation(true);

6.8 设置经纬度属性

1.10.1 及以后的版本可以通过 setGPSLocation方法,把第三方定位获取到的经纬度信息设置给 SDK, 设置之后经纬度信息记录在事件的 $longitude$latitude 属性中。

//设置经纬度
SensorsDataAPI.sharedInstance().setGPSLocation(latitude,longitude);

6.9 设置动态公共属性

2.0.1 及以后的版本可以通过 registerDynamicSuperProperties方法设置动态公共属性,设置之后 SDK 会自动获取 getDynamicSuperProperties 中的属性添加到触发的事件中。

// 初始化 SDK 后,设置动态公共属性
SensorsDataAPI.sharedInstance().registerDynamicSuperProperties(new SensorsDataDynamicSuperProperties() {
    @Override
    public JSONObject getDynamicSuperProperties() {
        try {
            // 比如 isLogin() 是用于获取用户当前的登录状态,SDK 会自动获取 getDynamicSuperProperties 中的属性添加到触发的事件中。
            boolean bool = isLogin();
            return new JSONObject().put("isLogin",bool);
        } catch (Exception e) {
            e.printStackTrace();
        }
        return null;
    }
});

6.10 删除本地存储的所有事件

3.1.5 及以后的版本可以通过 deleteAll方法,删除 App 本地存储的所有事件。

如果不是特殊要求,请不要调用此方法。

//删除 App 本地存储的所有事件
SensorsDataAPI.sharedInstance().deleteAll();

6.11 设置自签证书

3.1.2 及以后的版本可以通过 setSSLSocketFactory方法设置自签证书。

在 SDK 初始化后,调用 setSSLSocketFactory(SSLSocketFactory sslSocketFactory) ,设置 javax.net.ssl.SSLSocketFactory 实例进入 SDK,此时 SDK 内所有的 HTTPS 请求会进行此接口设置的证书校验。

以 DER 格式的证书为例:

try {
    //构建 SSLSocketFactory 实例
    SSLSocketFactory sslSocketFactory ;
    CertificateFactory cf = CertificateFactory.getInstance("X.509");
    // 其中 R.raw.ca 是您这边自签证书的公钥
    InputStream in = getResources().openRawResource(R.raw.ca);
    Certificate ca = cf.generateCertificate(in);
    try {
        in.close();
    } catch (Exception e) {
        e.printStackTrace();
    }
    KeyStore keystore = KeyStore.getInstance(KeyStore.getDefaultType());
    keystore.load(null, null);
    keystore.setCertificateEntry("ca", ca);
    String tmfAlgorithm = TrustManagerFactory.getDefaultAlgorithm();
    TrustManagerFactory tmf = TrustManagerFactory.getInstance(tmfAlgorithm);
    tmf.init(keystore);
    // Create an SSLContext that uses our TrustManager
    SSLContext sslContext = SSLContext.getInstance("TLS");
    sslContext.init(null, tmf.getTrustManagers(), null);
    sslSocketFactory = sslContext.getSocketFactory();
    //将实例传入神策
    SensorsDataAPI.sharedInstance().setSSLSocketFactory(sslSocketFactory);
} catch (Exception e) {
    e.printStackTrace();
}

关于 SSL 的更多内容可以参考 谷歌使用文档

7. 设置神策分析 SDK

当需要更精细地控制神策分析以通过以下选项设置数据采集功能。

7.1 数据采集

在每次调用 track()login()profileSet() 等方法的时,神策分析 SDK 会将事件与属性保存在 App 的存储空间中,并会检查如下条件,以判断是否向服务器上传数据:

  • 是否是WIFI/2G/3G/4G/5G网络条件
  • 是否满足发送条件之一:
    1. 与上次发送的时间间隔是否大于 flushInterval
    2. 本地缓存日志数目是否大于 flushBulkSize

默认的 flushBulkSize 为 100 条,默认的 flushInterval 为 15 秒。满足条件后,神策分析 SDK 会将数据 gzip 压缩后,批量发送到神策分析。

如果追求数据采集的时效性,可以调用 flush() 方法,强制将数据发送到神策分析,例如:

// 记录用户登录事件
SensorsDataAPI.sharedInstance().track("UserLogin");

// 强制发送数据
SensorsDataAPI.sharedInstance().flush();

在 App 进入后台状态时,SDK 会调用 flush() 方法,将缓存的数据发送到神策分析。

7.2 设置同步数据时的网络策略

默认情况下,在 WIFI/3G/4G/5G 网络条件下,SDK 都会尝试去同步数据。1.7.2及以后的版本支持可以自定义同步数据的网络策略。 通过 setFlushNetworkPolicy 方法来指定发送数据的网络策略 。

例如:

//网络模式选项
//SensorsDataAPI.NetworkType.TYPE_2G     2G网络下发送数据
//SensorsDataAPI.NetworkType.TYPE_3G     3G网络下发送数据
//SensorsDataAPI.NetworkType.TYPE_4G     4G网络下发送数据
//SensorsDataAPI.NetworkType.TYPE_5G     5G网络下发送数据
//SensorsDataAPI.NetworkType.TYPE_WIFI   WIFI网络下发送数据
//SensorsDataAPI.NetworkType.TYPE_ALL    2G/3G/4G/5G/WIFI网络下发送数据
//SensorsDataAPI.NetworkType.TYPE_NONE   所有网络下都不发送数据

//指定只在 3G/4G/WIFI 条件下发送数据。
SensorsDataAPI.sharedInstance().setFlushNetworkPolicy(SensorsDataAPI.NetworkType.TYPE_3G|SensorsDataAPI.NetworkType.TYPE_4G|SensorsDataAPI.NetworkType.TYPE_WIFI);

7.3 设置本地缓存上限值

SDK 本地数据库默认缓存数据的上限值为 32MB。 1.7.4及以后的版本支持通过 setMaxCacheSize 方法来设定缓存数据的上限值。参数单位 byte。

SAConfigOptions saConfigOptions = new SAConfigOptions(SA_SERVER_URL);
//在初始化时,利用 SAConfigOptions 设置本地数据缓存上限值为16MB
saConfigOptions.setMaxCacheSize(16 * 1024 * 1024);
  • 3.1.0 及之前的版本,设置缓存方式:

当存储数量达到上限值,会依次丢弃老数据,保留最新的数据

7.4 开启 SDK 调试日志

可以通过 enableLog 方法来开启 SDK 调试日志。开启后可通过 Android Studio Logcat 查看输出的 log,或用 adb logcat 查看日志。过滤日志关键字为:SA.,一个事件有两条日志。 日志中如果出现 track event 字段, 说明此事件已触发,如果出现 valid message 字段,说明数据已同步到服务端。

//开启调试日志
SensorsDataAPI.sharedInstance().enableLog(true);

7.5 修改 SDK 配置参数

修改 app/src/main/AndroidManifest.xml,在 <application> 标签中,添加 <meta-data> 项,可以修改 SDK 的默认参数,支持的选项如下:

  • com.sensorsdata.analytics.android.FlushInterval - 设置 SDK 的 flushInterval,单位毫秒,默认值为 15 秒;

  • com.sensorsdata.analytics.android.FlushBulkSize - 设置 SDK 的 flushBulkSize,默认值为 100;

  • com.sensorsdata.analytics.android.ResourcePackageName - 设置 App 的 Package Name,默认值为 Application 对象的 Package Name,当 App 的 R.* class 的 Package Name 与 Application不同时,需要手动填入该配置;

例如,设置神策分析 SDK 的 flushInterval 为 30 秒,flushBulkSize 为 50 条,关闭 Toast 提示:

<application>
    <meta-data
        android:name="com.sensorsdata.analytics.android.FlushInterval"
        android:value="30000" />
    <meta-data
        android:name="com.sensorsdata.analytics.android.FlushBulkSize"
        android:value="50" />
    <meta-data
        android:name="com.sensorsdata.analytics.android.ShowDebugInfoView"
        android:value="false" />
</application>

也可以利用代码,修改 FlushIntervalFlushBulkSize:

SAConfigOptions saConfigOptions = new SAConfigOptions(SA_SERVER_URL);
//在初始化时,利用 SAConfigOptions 设置相关参数
// 每缓存 50 条日志发送一次
saConfigOptions.setFlushBulkSize(50);
// 设置每 30 秒发送一次
saConfigOptions.setFlushInterval(30000);
  • 3.1.0 及之前的版本,设置相关参数:

7.6 调试查看埋点数据

3.0.4及以后的版本, SDK 调试模式默认为关闭状态,需在代码中配置 scheme 后,通过扫描神策分析「设置调试模式」的二维码开启调试模式; 开启调试模式只针对当前扫码打开的 App 有效,若 App 退到后台,杀掉(划掉) App 后,再次打开 App , SDK 的调试模式恢复为关闭状态。

7.6.1 获取并配置 scheme

获取 scheme

使用 admin 账号,登录到神策分析相应的项目,点击右上角的账号,从「数据接入」页面获取 scheme 的值。

配置 scheme

AndroidManifestMainActivity 的标签内,配置 scheme :

<activity android:name=".SplashActivity">
    <intent-filter>
        <action android:name="android.intent.action.MAIN" />
        <category android:name="android.intent.category.LAUNCHER" />
    </intent-filter>
</activity>

<activity android:name=".MainActivity">
    <!-- 在主 Activity 中配置 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:host="debugmode"
            android:scheme="您项目的 scheme 值" />
    </intent-filter>
</activity>

7.6.2 用手机自带的浏览器扫码打开 App,选择调试模式

在神策分析 v1.13 及之后版本中点击「设置设备调试模式」打开二维码。

二维码位置:「神策分析」——「埋点」——「导入实时查看」——「Debug 数据」——「设置设备调试模式」

扫码打开 App 时,会弹出提示,选择想要切换的调试模式。

开启调试模式(导入数据):打开调试模式,校验数据,并将数据导入到神策分析中。

开启调试模式(不导入数据):打开调试模式,仅校验数据,但不进行数据导入,数据最终不会进入到数据库。

7.6.3 导入实时查看

开启调试模式后,神策分析会弹出下图页面,点击「开始刷新」可以查看当前设备的调试数据上报情况

7.6.4 查看本地日志

开启调试模式后,也可以通过 Android Studio Logcat 查看输出的 log,或用 adb logcat 查看日志。过滤日志关键字为:SA.,一个事件有两条日志。 日志中如果出现 track event 字段, 说明此事件已触发,如果出现 valid message 字段,说明数据已同步到服务端。

8 预置属性

8.1 所有事件都会有的预置属性:

字段名称 类型 显示名 说明 版本
$app_version 字符串 应用版本 应用的版本
$lib 字符串 SDK类型 例如 Android
$lib_version 字符串 SDK版本
$manufacturer 字符串 设备制造商 例如 Xiaomi
$model 字符串 设备型号 例如 Redmi 4X
$os 字符串 操作系统 例如 Android
$os_version 字符串 操作系统版本 例如 6.0.1
$screen_height 数值 屏幕高度 例如 1280
$screen_width 数值 屏幕宽度 例如 720
$wifi BOOL 是否wifi
$carrier 字符串 运营商名称 例如 中国联通
$network_type 字符串 网络类型 例如 4G
$is_first_day 布尔值 是否首日访问 1.6.27支持
$device_id 字符串 设备ID 获取值为 AndroidId 1.7.1支持

8.2 $AppStart(App 启动) 事件的预置属性

字段名称 类型 显示名 说明 版本
$is_first_time BOOL 是否首次访问 App 安装后是否首次启动
$resume_from_background BOOL 是否从后台唤醒 App 是否是从后台恢复
$title 字符串 页面标题 Activity 的标题(仅 Android 端有)
$screen_name 字符串 页面名称 Activity 的包名.类名(仅 Android 端有)

注意:在 2.0.3 及以上的版本中,$AppStart 的计算规则默认为 30 秒的 session 机制。

8.3 $AppEnd(App 退出) 事件的预置属性

字段名称 类型 显示名 说明 版本
event_duration 数值 event_duration 本次 App 启动的使用时长(此字段虽没加 $ 符,也是预置字段)
$title 字符串 页面标题 Activity 的标题(仅 Android 端有)
$screen_name 字符串 页面名称 Activity 的包名.类名(仅 Android 端有)

8.4 $AppViewScreen(App 浏览页面) 事件的预置属性

字段名称 类型 显示名 说明 版本
$title 字符串 页面标题 Activity 的标题
$screen_name 字符串 页面名称 Activity 的包名.类名

8.5 $AppClick(App 元素点击) 事件的预置属性

字段名称 类型 显示名 说明 版本
$element_id 字符串 元素 ID 控件的ID
$element_type 字符串 元素类型 控件的类型,例如 Button
$element_content 字符串 元素内容 控件的内容
$title 字符串 页面标题 Activity 的标题
$screen_name 字符串 页面名称 Activity 的包名.类名
$element_position 字符串 元素位置 元素被点击时所处的位置

注意:只有控件本身有 position 时才有 $element_position 字段,例如 ListView 的 item。另外,控件本身有 id、text 属性时,对应的 App 元素点击事件才有 $element_id、$element_content 属性。