Android SDK 支持包括安装、启动、关闭、页面浏览、元素点击等在内事件的自动采集。

1.介绍

GravityEngineSDK 提供自动化收集数据的接口，您可根据业务需求自行选择需要自动收集的数据。

目前支持的自动采集事件类型有：

安装事件（$AppInstall）：记录 APP 被安装的行为
启动事件（$AppStart）：包括打开 APP 和从后台打开 APP
关闭事件（$AppEnd）：包括关闭 APP 和 App 进入后台，同时收集启动的时长
浏览事件（$AppView）：用户在 APP 中浏览页面（Activity）
点击事件（$AppClick）：用户在 APP 中点击控件
崩溃事件（$AppCrash）：APP 发生崩溃时记录崩溃信息

由于$AppInstall、$AppStart、$AppEnd的特殊性，SDK 会默认采集，且不可关闭！

接下来将会对每种类型的自采集事件做详细介绍。

2.开启自动采集

您需要手动调用enableAutoTrack，来打开自动采集功能：

List<GravityEngineSDK.AutoTrackEventType> typeList = new ArrayList<>();
typeList.add(GravityEngineSDK.AutoTrackEventType.APP_CRASH);
typeList.add(GravityEngineSDK.AutoTrackEventType.APP_VIEW_SCREEN);
typeList.add(GravityEngineSDK.AutoTrackEventType.APP_CLICK);
gravityEngineSDKInstance.enableAutoTrack(typeList);

如果您需要采集控件点击事件或者 Fragment 浏览事件，需要集成自动采集插件，详情见可选插件

3.详细介绍

3.1 安装事件

APP 安装事件将会记录 APP 的实际安装，在 APP 启动时上报，事件触发时间是 APP 安装后首次启动的时间，APP 升级并不会触发安装事件，而删除重装后会上报安装事件。

事件英文名：$AppInstall

3.2 启动事件

APP 启动事件将会在用户开启 APP 时触发。

事件英文名：$AppStart

3.3 关闭事件

APP 关闭事件将会在用户关闭 APP，或将 APP 调至后台时触发。

事件英文名：$AppEnd
预置属性：$event_duration，数值型，表示该次 APP 访问（自启动至结束）的时长，单位是秒。

3.4 浏览页面事件

APP 浏览页面事件会在用户浏览页面（Activity）时触发。

事件英文名：$AppView
预置属性：
- $screen_name，字符串型，为 Activity 的包名.类名
- $title，字符串型，为 Activity 的标题，取值为 Activity 的 title 属性的值

页面浏览事件中可以加入其它属性以扩展其分析价值，以下是自定义浏览页面事件的属性的方法

3.4.1 开启自动采集 Fragment 的页面浏览事件

在 SDK 初始化完成后，调用以下方法启动 Fragment 的自动采集功能

对于 android.support.v4.app.Fragment 的 Fragment

gravityEngineSDKInstance.trackFragmentAppViewScreen();

对于 android.app.Fragment 的 Fragment

// targetFragment 可替换为需要上传页面浏览事件的 Fragment
gravityEngineSDKInstance.trackViewScreen(targetFragment);

3.4.2 自定义页面浏览事件的属性

对于 Activity 的页面浏览事件，可以通过实现接口 ScreenAutoTracker 的方法增加属性，通过以下两个方法，可以为页面浏览事件增加页面 URL 信息，以及其他自定义属性：

public class MainActivity extends AppCompatActivity implements ScreenAutoTracker {
    private Context mContext;

    @Override
    public String getScreenUrl() {
        return "gravityengine://page/main";
    }

    @Override
    public JSONObject getTrackProperties() throws JSONException {
        JSONObject jsonObject = new JSONObject();
        jsonObject.put("param1", "ABCD");
        jsonObject.put("param2", "gravityengine");
        return jsonObject;
    }
}

getScreenUrl的返回值将作为该Activity的 URL Schema，当触发该页面的浏览事件时，将会加入预置属性$url，取值即为当前页面的 URL Schema；同时 SDK 会取跳转前页面的 URL Schema，如果能取到则会加入到预置属性$referrer中则为前向地址。
getTrackProperties的返回值是该页面的浏览事件的自定义属性，将会自动加入到该页面的浏览事件中

对于 Fragment 的页面浏览事件，我们提供两种方式添加属性

通过 @GravityEngineFragmentTitle 方式添加属性

@GravityEngineFragmentTitle(title = "myFragment")
public class ListViewFragment extends BaseFragment {
  // your fragment implementations
}

通过 ScreenAutoTracker 接口添加属性

@Override
public JSONObject getTrackProperties() {
    try {
        JSONObject properties = new JSONObject();
        properties.put("$title", "RecyclerViewFragment");
        return properties;
    } catch (JSONException e) {
        // ignore
    }
    return null;
}

3.5 点击事件

APP 控件点击事件将会在用户点击控件（view）时触发

事件英文名：$AppClick
预置属性：
- $screen_name，字符串型，为控件所属 Activity 的包名.类名
- $title，字符串型，为控件所属 Activity 的标题，取值为 Activity 的 title 属性的值
- $element_content，字符串型，为控件的内容
- $element_type，字符串型，为控件的类型
- $element_id，字符串型，为控件的 ID，默认使用 android:id
- $element_position，字符串型，当控件存在 position 时才会上传
- $element_selector，字符串型，为控件的 viewPath 的拼接

对于页面上 View 的点击事件，有以下多种方式来设置更多属性，以扩展其分析价值：

3.5.1 自定义控件 ID

控件的 ID 默认使用 android:id，如果该属性无法取到，或者希望自定义控件 ID，可以使用以下方法覆盖 $element_id 属性

gravityEngineSDKInstance.setViewID(view,viewID);

对于 Dialog ，可以使用如下方法：

//android.app.Dialog
gravityEngineSDKInstance.setViewID(view,viewID);

或者

//android.support.v7.app.AlertDialog
gravityEngineSDKInstance.setViewID(view,viewID);

参数 view 为需要设置控件 ID 的 view，参数 viewID 为设置的控件 ID，当上传该控件的点击事件时，$element_id 的取值即为此处的传入值

3.5.2 自定义控件点击事件的属性

您可以通过以下方法，为某控件（view）的点击事件增加自定义属性：

gravityEngineSDKInstance.setViewProperties(view,properties);

参数 view 为需要设置自定义属性的 view，参数 properties ，类型为 JSONObject ，为设置的自定义属性，当上传该控件的点击事件时，将会添加这些属性。

另外，对于 ExpandableListView 、ListView 与 GridView ，还可以通过 Adapter 实现接口的方式，来增加点击某 item 时的自定义属性。

ExpandableListView 需实现 GravityExpandableListViewItemTrackProperties 接口

public interface GravityExpandableListViewItemTrackProperties {
    /**
     * 增加点击 groupPosition、childPosition 处 item 时的属性
     * @param groupPosition
     * @param childPosition
     * @return
     * @throws JSONException
     */
    JSONObject getGravityChildItemTrackProperties(int groupPosition, int childPosition) throws JSONException;

    /**
     * 增加点击 groupPosition 处 item 时的属性
     * @param groupPosition
     * @return
     * @throws JSONException
     */
    JSONObject getGravityGroupItemTrackProperties(int groupPosition) throws JSONException;
}

ListView 与 GridView 需实现 GravityAdapterViewItemTrackProperties 接口

public interface GravityAdapterViewItemTrackProperties {
    /**
     * 增加点击 position 处 item 时的属性
     * @param position
     * @return
     * @throws JSONException
     */
    JSONObject getGravityItemTrackProperties(int position) throws JSONException;
}

3.5.3 对 AlertDialog 的点击事件增加页面（Activity）信息

对于 AlertDialog（android.app.AlertDialog与android.support.v7.app.AlertDialog）的点击事件，可以通过以下方法绑定所属页面（Activity），在其点击事件中将会加入所属页面的 $screen_name 与 $title 属性。

通过调用 dialog.show()显示 dialog，请使用以下方法：

dialog.setOwnerActivity(targetActivity);

通过调用 builder.show()显示 dialog，请使用以下方法:

builder.show().setOwnerActivity(activity);

3.5.4 通过注解@GravityEngineTrackViewOnClick 上传控件点击事件

如果您使用的是 android:onClick 为控件（view）添加点击事件的调用方法，则可以在调用方法上添加注解@GravityEngineTrackViewOnClick，当该调用方法被执行时，SDK 将会上传控件点击事件

@GravityEngineTrackViewOnClick
public void buttonOnClick(View v){}

如果方法 buttonOnClick 被调用，则会上传控件点击事件

3.6 崩溃事件

当 APP 出现未捕获异常时，会上报 APP 崩溃事件

事件英文名：$AppCrash
预置属性：$app_crashed_reason，字符型，记录崩溃时的堆栈轨迹

4.忽略自动采集事件

您可以通过以下方式，忽略某页面或控件的自动采集事件

4.1 忽略页面的自动采集事件

对于某些页面（Activity），如果不想传输自动采集事件（包括页面浏览与控件点击事件），可以通过以下方法进行忽略：

//单页面的忽略
gravityEngineSDKInstance.ignoreAutoTrackActivity(MainActivity.class);
//多页面的忽略
List<Class<?>> classList = new ArrayList<>();
classList.add(MainActivity.class);
gravityEngineSDKInstance.ignoreAutoTrackActivities(classList);

也可以在Activity或Fragment前添加注解@GravityEngineIgnoreTrackAppViewScreen，忽略某个 Activity 或 Fragment 的页面浏览事件

//忽略 TestActivity 的页面浏览事件
@GravityEngineIgnoreTrackAppViewScreen
public class TestActivity extends AppCompatActivity {
    ...
}

在Activity前添加注解@GravityEngineIgnoreTrackAppViewScreenAndAppClick，忽略某个 Activity 页面浏览事件与该页面下的控件点击事件

//忽略 TestActivity 的页面浏览事件与该页面下的控件点击事件
@GravityEngineIgnoreTrackAppViewScreenAndAppClick
public class TestActivity extends AppCompatActivity {
    ...
}

4.2 忽略某个类型控件的点击事件

如果需要忽略某个类型控件的点击事件，可以使用以下方法进行忽略

gravityEngineSDKInstance.ignoreViewType(ignoredClass);

ignoredClass即为需要忽略的控件类型，比如Dialog、Checkbox等

4.3 忽略某个元素（View）的点击事件

如果希望忽略某个元素（View）的点击事件，可以使用以下方法进行忽略

gravityEngineSDKInstance.ignoreView(targetView);

targetView即为需要忽略的 View

5.使用注解快速设置事件

如果需要监控某个方法的调用次数，或者某方法一经调用即需要上传一个事件，则可以使用注解@GravityEngineTrackEvent快速设置需要上传的事件，需要注意的是，属性无法传入变量，因此只适合上传简单的事件

//使用注解
@GravityEngineTrackEvent(eventName = "event_name", properties = "{\"paramString\":\"value\",\"paramNumber\":123,\"paramBoolean\":true}")
public void fun(){}

此时如果方法 fun 被调用，则会上传一个事件名为event_name，属性为"paramString":"value"、"paramNumber":123 与 "paramBoolean":true 的事件

6.设置自定义属性

您可以调用 enableAutoTrack(List<GravityEngineSDK.AutoTrackEventType>, JSONObject)，打开自动采集功能，同时设置自定义属性

JSONObject properties = new JSONObject();
try {
    properties.put("auto_self_define_key", "auto_self_define_value");
} catch (Exception e) {
    e.printStackTrace();
}
gravityEngineSDKInstance.enableAutoTrack(typeList, properties);

您也可以调用 setAutoTrackProperties(List<GravityEngineSDK.AutoTrackEventType>, JSONObject)，设置或者更新自定义属性

JSONObject properties = new JSONObject();
try {
    properties.put("auto_self_define_key", "auto_self_define_value");
} catch (Exception e) {
    e.printStackTrace();
}
gravityEngineSDKInstance.setAutoTrackProperties(typeList, properties);

7.自动采集事件设置回调

您可以通过设置回调，在已开启的自动采集事件发生时，获取到当前事件的事件类型以及所携带的事件属性，并且可以通过设置返回值的方式为该事件增加额外需要上报的属性。

List<GravityEngineSDK.AutoTrackEventType> typeList = new ArrayList<>();
typeList.add(GravityEngineSDK.AutoTrackEventType.APP_INSTALL);
typeList.add(GravityEngineSDK.AutoTrackEventType.APP_END);

gravityEngineSDKInstance.enableAutoTrack(typeList, new GravityEngineSDK.AutoTrackEventListener() {
    @Override
    public JSONObject eventCallback(GravityEngineSDK.AutoTrackEventType eventType, JSONObject properties) {
        try {
            return new JSONObject("{\"keykey\":\"value1111\"}");
        } catch (JSONException e) {
            e.printStackTrace();
            return null;
        }
    }
});

8.可选插件

只有当您需要开启控件点击事件和 Fragment 页面浏览事件时，才需要集成此插件。

buildscript {
    repositories {
        google()
        jcenter()
    }
    dependencies {
        classpath 'cn.gravity.android:android-gradle-plugin-autotrack:${PLUGIN_LATEST_VERSION}'
    }
}

PLUGIN_LATEST_VERSION 请参见下方的发版记录

可以在项目 build.gradle 文件中配置插件相关参数

apply plugin: 'cn.gravity.android'
android {
}
GravityEngineSDK {
    // 打开编译日志
    debug = false
    //是否允许扫描jar
    disableJar = false
    //是否扫描指定的类，默认全部扫描
    useInclude = false
    //指定的类列表，useInclude为true时有效
    include = []
    //指定排除的类列表，useInclude为false时有效
    exclude = []
}

如果想打开编译日志，可以设置 debug = true，默认为 false
如果想禁止扫描 jar 中的类，可以设置 disableJar = true，默认是 false
如果不想扫描某个路径下的类，可以通过设置 exclude = ['cn.test.android','android.support']，默认全局扫描
也可以通过设定 useInclude = true，开启指定类列表扫描模式，这时需要使用 include 来说明哪些类自动添加埋点

9.发版记录

版本	日期	备注
1.1.2	2025-11-12	支持更多kotlin语法解析
1.0.8	2025-09-10	修复 kotlin 包的概率的打包失败
1.0.7	2023-03-16	支持全埋点自采集方案

进阶功能