Android SDK 快速接入

最后更新于:2019-10-12 18:04:10

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

更多参数接口信息介绍可前往 Android SDK 使用说明

1、事件设计表(示例)

2、集成 SDK

3、埋点示例

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

1. 事件设计表(示例)

事件设计表一般是由神策分析师和你们对接的同事,针对具体业务需求一起梳理的需要做埋点的 Excel 表。 神策分析系统宏观上有两张表,事件表(events)用于记录用户的行为事件,比如 App 启动,App 浏览页面;用户表(users)用于保存用户相关的一些信息,比如个人资料。

事件和用户属性设计
事件表(events) 用户表(users)
事件名(带 $ 符号的为神策预置事件,开启全埋点自动采集) 事件属性 用户属性
App 启动事件( $AppStart ) 预置事件属性 邮箱( email )
App 退出事件( $AppEnd ) 预置事件属性
App 浏览页面事件( $AppViewScreen ) 预置事件属性
App 元素点击事件( $AppClick ) 预置事件属性
搜索事件( search ) 搜索关键词( searchKeyWord )

2. 集成 SDK

神策 SDK 提供了 全埋点 的功能,可以帮您采集四类事件:

事件显示名 事件名 事件描述
App 启动事件 $AppStart App 启动时触发
App 退出事件 $AppEnd SDK 在 2.0.3 版本加入了 30 秒的 session 机制,App 退到后台 30 秒的时候,才会触发退出事件, 之后再启动 App,才会触发启动事件
App 浏览页面事件 $AppViewScreen Activity onResume 时触发(如果开启了 Fragment 浏览页面事件,Fragment 处于用户可见时触发)
App 元素点击事件 $AppClick 控件被点击时触发

Gradle 编译环境(Android Studio)

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

buildscript {
    repositories {
        jcenter()
    }
    dependencies {
        classpath 'com.android.tools.build:gradle:2.2.3'
        //添加 Sensors Analytics android-gradle-plugin 依赖
        classpath 'com.sensorsdata.analytics.android:android-gradle-plugin2:3.1.6'
    }
}

allprojects {
    repositories {
        jcenter()
    }
}

如下示例图:

第二步:主 module 的 build.gradle 文件中添加 com.sensorsdata.analytics.android 插件、Sensors Analytics 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.6'
}

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

如下示例图:

  1. 下载 Android SDK 源码
  2. 将 SensorsAnalyticsSDK 以 module 的形式添加到项目中

在程序的入口 Application 的 onCreate() 中调用 SensorsDataAPI.startWithConfiguration() 在主线程中初始化 SDK。 SDK 可以自动采集一些用户行为,如 App 启动、退出、浏览页面、控件点击等。初始化 SDK 后,可以通过 SAConfigOptions 来设置自动采集的事件。

import android.app.Application;
import android.content.Context;
import android.content.pm.ApplicationInfo;
import android.content.pm.PackageInfo;
import android.content.pm.PackageManager;
import com.sensorsdata.analytics.android.sdk.SAConfigOptions;
import com.sensorsdata.analytics.android.sdk.SensorsAnalyticsAutoTrackEventType;
import com.sensorsdata.analytics.android.sdk.SensorsDataAPI;
import org.json.JSONObject;


public class App extends Application {

    // debug 模式的数据接收地址 (测试,测试项目)
    final static String SA_SERVER_URL_DEBUG = "【测试项目】数据接收地址";

    // release 模式的数据接收地址(发版,正式项目)
    final static String SA_SERVER_URL_RELEASE = "【正式项目】数据接收地址";


    @Override
    public void onCreate() {
        super.onCreate();
        // 在 Application 的 onCreate 初始化 SDK
        initSensorsDataSDK();
    }

    /**
     * 初始化 SDK 、设置自动采集、设置公共属性
     */
    private void initSensorsDataSDK() {
        try {
            // 设置 SAConfigOptions,传入数据接收地址 SA_SERVER_URL
            SAConfigOptions saConfigOptions = new SAConfigOptions(isDebugMode(this) ? SA_SERVER_URL_DEBUG : SA_SERVER_URL_RELEASE);

            // 通过 SAConfigOptions 设置神策 SDK 自动采集 options
            saConfigOptions.setAutoTrackEventType(
                            SensorsAnalyticsAutoTrackEventType.APP_START | // 自动采集 App 启动事件
                            SensorsAnalyticsAutoTrackEventType.APP_END | // 自动采集 App 退出事件
                            SensorsAnalyticsAutoTrackEventType.APP_VIEW_SCREEN | // 自动采集 App 浏览页面事件
                            SensorsAnalyticsAutoTrackEventType.APP_CLICK)   // 自动采集控件点击事件
                    .enableLog(isDebugMode(this))        // 开启神策调试日志,默认关闭(调试时,可开启日志)。
                    .enableTrackAppCrash(); // 开启 crash 采集

            // 需要在主线程初始化神策 SDK
            SensorsDataAPI.startWithConfiguration(this, saConfigOptions);

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

    /**
     * @param context App 的 Context
     *                获取应用程序名称
     */
    public static CharSequence getAppName(Context context) {
        if (context == null) {
            return "";
        }
        try {
            PackageManager packageManager = context.getPackageManager();
            if (packageManager == null) {
                return "";
            }
            ApplicationInfo appInfo = packageManager.getApplicationInfo(context.getPackageName(),
                    PackageManager.GET_META_DATA);
            return appInfo.loadLabel(packageManager);
        } catch (Exception e) {
             e.printStackTrace();
        }
        return "";
    }

    /**
     * @param context App 的 Context
     * @return debug return true,release return false
     * 用于判断是 debug 包,还是 relase 包
     */
    public static boolean isDebugMode(Context context) {
        try {
            ApplicationInfo info = context.getApplicationInfo();
            return (info.flags & ApplicationInfo.FLAG_DEBUGGABLE) != 0;
        } catch (Exception e) {
            e.printStackTrace();
            return false;
        }
    }
}

数据接收地址 server_url 获取方式

3. 埋点示例

3.1 追踪事件

可以通过 track() 方法追踪用户行为事件,并为事件添加自定义属性(触发的事件会存储到神策分析系统的 events 表中)。

    try {
        JSONObject properties = new JSONObject();
        properties.put("searchKeyWord", "神策数据");// 搜索关键字
        // 记录搜索(search )事件
        SensorsDataAPI.sharedInstance().track("search", properties);
    } catch (JSONException e) {
        e.printStackTrace();
    }

3.2 设置用户属性

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

    try {
        JSONObject properties = new JSONObject();
        properties.put("email", "xxx@xxx.xx");
        // 设置用户的 email
        SensorsDataAPI.sharedInstance().profileSet(properties);
    } catch (JSONException e) {
        e.printStackTrace();
    }

3.3 匿名 ID 和登录 ID 关联

如何准确的标识用户

成功关联设备 ID登录 ID 之后,用户在该设备 ID 上或该登录 ID 下的行为就会贯通,被认为是一个神策 ID 发生的。在进行事件、漏斗、留存等用户相关分析时也会算作一个用户。

关联设备 ID登录 ID 的方法虽然实现了更准确的用户追踪,但是也会增加埋点接入的复杂度。所以一般来说,我们建议只有当同时满足以下条件时,才考虑进行 ID 关联:

  1. 需要贯通一个用户在一个设备上注册前后的行为。
  2. 需要贯通一个注册用户在不同设备上登录之后的行为

用户在登录前 ,SDK 会分配一个匿名 ID 来标识游客。当用户注册成功或登录成功时调用 login 方法,传入对应的登录 ID ;匿名 ID 会与对应的登录 ID 进行关联,关联成功之后视为同一个用户。 调用时机:注册成功、登录成功 、初始化 SDK(如果能获取到登录 ID)都需要调用 login 方法传入登录 ID。

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

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

注意: 如果服务端做了埋点,需在用户注册/登录的时候将匿名 ID 传给服务端做用户 ID 关联。 可以通过 getAnonymousId 方法 获取 SDK 分配的 匿名 ID

//在用户注册或登录时,获取当前用户的匿名 ID 传给服务端
String AnonymousId=SensorsDataAPI.sharedInstance().getAnonymousId();

3.4 调试查看埋点数据

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

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

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

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

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

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

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

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

3.4.3 导入实时查看

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

3.4.4 查看本地日志

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

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