Android SDK 快速接入

最后更新于:2019-03-06 18:32:33

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

Android 安卓全埋点 技术白皮书下载

1. 事件设计表(示例)

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

事件设计表(示例)
事件表 用户表
事件名 事件属性 数据类型 用户属性 数据类型
ViewProduct ( 浏览商品 ) ProductName ( 商品名称 ) 字符串(String) name ( 姓名 ) 字符串(String)
ProductPrice ( 商品价格 ) 数值(Number) gender ( 性别 ) 字符串(String)

2. Android SDK 集成

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:3.0.2'
    }
}

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 {
   //添加 Sensors Analytics SDK 依赖
   implementation 'com.sensorsdata.analytics.android:SensorsAnalyticsSDK:3.0.3'
}

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

如下示例图:

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

3. Android SDK 使用

3.1 初始化 SDK

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

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.SensorsDataAPI;
import org.json.JSONObject;
import java.util.ArrayList;
import java.util.List;

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

    /**
     * 初始化 SDK 、设置公共属性、开启自动采集
     */
    private void initSensorsDataSDK(Context context) {
        try {
            // 初始化 SDK
            SensorsDataAPI.sharedInstance(
                    context,                                                                                  // 传入 Context
                    (isDebugMode = isDebugMode(context)) ? SA_SERVER_URL_DEBUG : SA_SERVER_URL_RELEASE      // 数据接收的 URL
                    );

            // 初始化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。

注意:用户 ID 是指可以唯一标识一个用户的 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. 调试查看埋点数据

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

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>

2、用手机浏览器扫码打开 App,选择调试模式

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

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

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

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

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

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

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