Android SDK

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

更新日志

新书推荐《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.0.4'
    }
}

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.1.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。

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

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

2. 初始化神策分析 SDK

2.1 获取配置信息

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

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

• 数据接收地址，建议使用不带端口号的: http://{$service_name}.datasink.sensorsdata.cn/sa?project={$project_name}&token={$project_token}

• 数据接收地址，带端口号的: http://{$service_name}.cloud.sensorsdata.cn:8106/sa?project={$project_name}&token={$project_token}

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

• 数据接收地址: http://{$host_name}:8106/sa?project={$project_name}

  （注：神策分析 1.7 及之前的版本，单机版私有部署默认端口号为 8006）

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

• 数据接收地址: http://{$host_name}:8106/sa?project={$project_name}

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

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

2.2 在 App 中使用

在程序的入口 Application 的 onCreate() 中调用 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 初始化方式：

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


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

    // Debug 模式选项
    //   SensorsDataAPI.DebugMode.DEBUG_OFF - 关闭 Debug 模式
    //   SensorsDataAPI.DebugMode.DEBUG_ONLY - 打开 Debug 模式，校验数据，但不进行数据导入
    //   SensorsDataAPI.DebugMode.DEBUG_AND_TRACK - 打开 Debug 模式，校验数据，并将数据导入到神策分析中
    // 注意！请不要在正式发布的 App 中使用 Debug 模式！
    final SensorsDataAPI.DebugMode SA_DEBUG_MODE = SensorsDataAPI.DebugMode.DEBUG_OFF;

    //初始化 SDK
    SensorsDataAPI.sharedInstance(
            this,                        // 传入 Context
            SA_SERVER_URL,               // 数据接收的 URL
            SA_DEBUG_MODE);             // Debug 模式选项

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

至此，我们已经可以正常使用神策分析 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 启动、退出、浏览页面、控件点击等。初始化 SDK 后，可以通过 enableAutoTrack 方法打开自动采集:

    try {
         // 打开自动采集, 并指定追踪哪些 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();
    }

打开 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，则获取 activity 的 android:label 属性。

  • $screen_name - String 类型，表示 Activity 的包名.类名

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

3.2 记录激活事件

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

例如，在启动页 Activity 的 onCreate 方法中申请权限：

    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 是属性的值，支持 String、Number、Boolean、JSONArray 和 Date，对于 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 本地缓存中。可以通过 unregisterSuperProperty() 删除一个公共属性，使用 clearSuperProperties() 会删除所有已设置的事件公共属性。

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

注意：请在开启自动采集（ enableAutoTrack ）之前调用 registerSuperProperties 方法，确保每个事件都会添加已设置的公共属性。

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", "App Store");

        // 设定用户渠道为，"[e-mail]" 的 "AdSource" 属性值为 "App Store"
        SensorsDataAPI.sharedInstance().profileSetOnce(properties);

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

        // 再次设定用户渠道，设定无效，"[e-mail]" 的 "AdSource" 属性值仍然是 "App 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 属性中。

    //开启 crash 信息收集
    SensorsDataAPI.sharedInstance().trackAppCrash();

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 删除本地存储的所有事件

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

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

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

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。

//设置本地数据缓存上限值为16MB
SensorsDataAPI.sharedInstance().setMaxCacheSize(16 * 1024 * 1024);

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

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>

也可以在程序执行过程中，随时修改 FlushInterval 和 FlushBulkSize:

    // 每缓存 50 条日志发送一次
    SensorsDataAPI.sharedInstance().setFlushBulkSize(50);

    // 设置每 30 秒发送一次
    SensorsDataAPI.sharedInstance().setFlushInterval(30000);

    //打开自动追踪
    SensorsDataAPI.sharedInstance().enableAutoTrack();

7.6 调试查看埋点数据

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

7.6.1 获取并配置 scheme

获取 scheme

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

配置 scheme

在 AndroidManifest 中 MainActivity 的标签内，配置 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 属性。