Android SDK 快速接入

最后更新于：2018-08-14 10:47:12

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

1. 事件设计表（示例）

事件设计表一般是由神策分析师和你们对接的同事，针对具体业务需求一起梳理的需要做埋点的 Excel 表。

事件设计表（示例）
事件表		用户表
事件名	事件属性	用户属性
ViewProduct ( 浏览商品 )	ProductName ( 商品名称 )	name ( 姓名 )
ViewProduct ( 浏览商品 )	ProductPrice ( 商品价格 )	gender ( 性别 )

2. Android SDK 集成

使用 Gradle 集成
源码集成

Gradle 编译环境（Android Studio）

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

buildscript {
    repositories {
        jcenter()
        //添加 Sensors Analytics maven 库地址
        maven {
            url 'https://dl.bintray.com/zouyuhan/maven'
        }
    }
    dependencies {
        classpath 'com.android.tools.build:gradle:2.2.3'
        //添加 Sensors Analytics android-gradle-plugin 依赖
        classpath 'com.sensorsdata.analytics.android:android-gradle-plugin2:2.0.0'
    }
}

allprojects {
    repositories {
        jcenter()
        //添加 Sensors Analytics maven 库地址
        maven {
            url 'https://dl.bintray.com/zouyuhan/maven'
        }
    }
}

如下示例图：

第二步：在 主 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 {
   implementation 'com.android.support:appcompat-v7:25.1.1'
   //添加 Sensors Analytics SDK 依赖
   implementation 'com.sensorsdata.analytics.android:SensorsAnalyticsSDK:2.0.0'
}

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

如下示例图：

第三步：由于 SDK 会依赖 appcompat-v7 处理下面几个控件：

android.support.v7.widget.SwitchCompat
android.support.v7.app.AlertDialog

需要添加下面依赖( 如果项目中已引入了 v7包，可以不添加 )：

implementation 'com.android.support:appcompat-v7:25.1.1'

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

3. Android SDK 使用

3.1 初始化 SDK

在程序的入口 Application 的 onCreate() 中调用 SensorsDataAPI.sharedInstance() 初始化 SDK：

public class App extends Application {

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

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

    // SDK Debug 模式选项
    //   SensorsDataAPI.DebugMode.DEBUG_OFF - 关闭 Debug 模式
    //   SensorsDataAPI.DebugMode.DEBUG_ONLY - 打开 Debug 模式，校验数据，但不进行数据导入
    //   SensorsDataAPI.DebugMode.DEBUG_AND_TRACK - 打开 Debug 模式，校验数据，并将数据导入到 Sensors Analytics 中
    // TODO 注意！请不要在正式发布的 App 中使用 DEBUG_AND_TRACK /DEBUG_ONLY 模式！ 请使用 DEBUG_OFF 模式！！！

    // debug 时，初始化 SDK 使用测试项目数据接收 URL 、使用 DEBUG_AND_TRACK 模式；release 时，初始化 SDK 使用正式项目数据接收 URL 、使用 DEBUG_OFF 模式。
    private boolean isDebugMode;

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

    /**
     * 初始化 SDK 、设置公共属性、开启自动采集
     */
    private void initSensorsDataSDK(Context context) {
        try {
            if(TextUtils.isEmpty("")){}

            // 初始化 SDK
            SensorsDataAPI.sharedInstance(
                    context,                                                                                  // 传入 Context
                    (isDebugMode = isDebugMode(context)) ? SA_SERVER_URL_DEBUG : SA_SERVER_URL_RELEASE,       // 数据接收的 URL
                    isDebugMode ? SensorsDataAPI.DebugMode.DEBUG_AND_TRACK : SensorsDataAPI.DebugMode.DEBUG_OFF); // Debug 模式选项

            // 初始化SDK后，获取应用名称设置为公共属性
            JSONObject properties = new JSONObject();
            properties.put("app_name", getAppName(context));
            SensorsDataAPI.sharedInstance().registerSuperProperties(properties);

            // 打开自动采集, 并指定追踪哪些 AutoTrack 事件
            List<SensorsDataAPI.AutoTrackEventType> eventTypeList = new ArrayList<>();
            // $AppStart
            eventTypeList.add(SensorsDataAPI.AutoTrackEventType.APP_START);
            // $AppEnd
            eventTypeList.add(SensorsDataAPI.AutoTrackEventType.APP_END);
            // $AppViewScreen
            eventTypeList.add(SensorsDataAPI.AutoTrackEventType.APP_VIEW_SCREEN);
            // $AppClick
            eventTypeList.add(SensorsDataAPI.AutoTrackEventType.APP_CLICK);
            SensorsDataAPI.sharedInstance().enableAutoTrack(eventTypeList);

        } catch (Exception e) {
            e.printStackTrace();
        }
    }

    /**
     * @param context App 的 Context
     *                获取应用程序名称
     */
    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;
        }
    }

    /**
     * @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;
        }
    }
}

3.2 开启全埋点

SDK 可以自动采集一些用户行为，如 App 启动、退出、浏览页面、控件点击等。初始化 SDK 后，可以通过 enableAutoTrack 方法打开自动采集:

    try {
         // 打开自动采集, 并指定追踪哪些自动采集事件
        List<SensorsDataAPI.AutoTrackEventType> eventTypeList = new ArrayList<>();
        // $AppStart
        eventTypeList.add(SensorsDataAPI.AutoTrackEventType.APP_START);
        // $AppEnd
        eventTypeList.add(SensorsDataAPI.AutoTrackEventType.APP_END);
        // $AppViewScreen
        eventTypeList.add(SensorsDataAPI.AutoTrackEventType.APP_VIEW_SCREEN);
        // $AppClick
        eventTypeList.add(SensorsDataAPI.AutoTrackEventType.APP_CLICK);
        SensorsDataAPI.sharedInstance().enableAutoTrack(eventTypeList);
    } catch (Exception e) {
        e.printStackTrace();
    }

3.3 track 自定义事件

可以通过 track() 方法追踪用户行为事件，并为事件添加自定义属性。以电商产品为例，可以这样追踪一次购物行为：

    // 用户浏览商品时...

    try {
        JSONObject properties = new JSONObject();
        properties.put("ProductName", "Redmi 4X");// 商品名称
        properties.put("ProductPrice", 666);    // 商品价格
        SensorsDataAPI.sharedInstance().track("ViewProduct", properties);
    } catch (JSONException e) {
        e.printStackTrace();
    }

3.4 匿名 ID 和用户 ID 关联

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

//注册成功、登录成功、初始化SDK后  调用 login 传入用户ID
SensorsDataAPI.sharedInstance().login("用户 ID");

3.5 设置用户属性

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

    try {
        JSONObject properties = new JSONObject();
        properties.put("gender", "Male");// 设定用户性别属性 gender 为 "Male"
        properties.put("name", "小神");// 设定用户姓名属性 name 为 "小神"
        SensorsDataAPI.sharedInstance().profileSet(properties);
    } catch (JSONException e) {
        e.printStackTrace();
    }

4. 调试查看埋点数据

1、打开调试日志

默认情况下， SDK 只会输出错误日志和 Debug 模式的提示信息。若开发者需要调试 SDK，可以调用 enableLog 方法开启调试日志：

    //开启调试日志（ true 表示开启调试日志）
    SensorsDataAPI.sharedInstance().enableLog(true);

2、为了便于调试查看数据 SDK Debug模式选用 DEBUG_AND_TRACK

3、通过 Android Studio Logcat 查看输出的 log，或用 adb logcat 查看日志。过滤日志关键字为：SA. 日志中如果出现 valid message 字段，说明数据已同步到服务端。

4、在埋点→导入数据实时查看中查看导入数据情况