神策分析 Android SDK AutoTrack 使用说明

最后更新于：2018-08-02 11:56:39

1. 自定义页面信息

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

3. 通过代码 track 浏览页面事件

4. AlertDialog

5. 忽略某个页面或某些页面的事件

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

7. 忽略某个View的点击事件

8. 设置元素ID

9. 自定义元素属性

10. 注解 @SensorsDataIgnoreTrackAppViewScreen

11. 注解 @SensorsDataTrackViewOnClick

12. 注解 @SensorsDataTrackEvent

13. 开启 React Native 页面控件的自动采集

14. TODO

配置

1. 自定义页面信息($AppViewScreen)

对于 App 中的核心页面（Activity），我们提供了一个 接口 ScreenAutoTracker：

public interface ScreenAutoTracker {
    /**
     * 返回当前页面的Url
     * 用作下个页面的referrer
     * @return String
     */
    String getScreenUrl();

    /**
     * 返回自定义属性集合
     * 我们内置了一个属性:$screen_name,代表当前页面名称, 默认情况下,该属性会采集当前Activity的CanonicalName,即:
     * activity.getClass().getCanonicalName(), 如果想自定义页面名称, 可以在Map里put该key进行覆盖。
     * 注意:screen_name的前面必须要要加"$"符号
     *
     * @return JSONObject
     * @throws JSONException JSONException
     */
    JSONObject getTrackProperties() throws JSONException;
}

当用户实现该接口时，SDK 会将 getTrackProperties 返回的属性（JSONObject类型）加入 $AppViewScreen 事件的属性中，作为用户访问该页面时的事件属性；SDK 会将 getScreenUrl 返回的字符串作为页面的 Url Schema，记录在 $AppViewScreen 事件的 $url 属性中，并且当用户切换页面时，将前一个页面中的 Url Schema 作为当前页面的 $AppViewScreen 事件的 $referrer 属性。

例如：

public class OrderDetailActivity extends Activity implements ScreenAutoTracker {
    @Override
    public String getScreenUrl() {
        return "sensorsdata://page/order/detail?orderId=888888";
    }

    @Override
    public JSONObject getTrackProperties() throws JSONException {
        JSONObject jsonObject = new JSONObject();
        jsonObject.put("orderId", "888888");
        jsonObject.put("manufacturer", "sensorsdata");
        return jsonObject;
    }
}

2. 开启 Fragment 页面浏览事件的自动采集($AppViewScreen)

从 1.7.10 可以使用 trackFragmentAppViewScreen 方法开启 Fragment 页面浏览事件的自动采集：

 //初始化 SDK 之后，开启自动采集 Fragment 页面浏览事件
SensorsDataAPI.sharedInstance().trackFragmentAppViewScreen();

从 1.8.10 开启 Fragment 页面浏览事件的自动采集,调用 trackFragmentAppViewScreen 方法后，还需在 BaseFragment （基类）上添加注解 @SensorsDataTrackFragmentAppViewScreen, 并在 BaseFragment 中重写下面三个方法：

@SensorsDataTrackFragmentAppViewScreen
public class BaseFragment extends Fragment {

    @Override
    public void onResume() {
        super.onResume();
    }

    @Override
    public void setUserVisibleHint(boolean isVisibleToUser) {
        super.setUserVisibleHint(isVisibleToUser);
    }

    @Override
    public void onHiddenChanged(boolean hidden) {
        super.onHiddenChanged(hidden);
    }
}

注意：目前只支持 android.support.v4.app.Fragment 的 Fragment 页面浏览事件。 开启了 Fragment 浏览页面的自动采集 ，可以通过注解 @SensorsDataIgnoreTrackAppViewScreen 忽略 Fragment 所在 Activity 的页面浏览事件；如果某些 Fragment 的页面浏览事件也不想采集，也可以通过此注解来忽略掉。

如果使用的是 android.app.Fragment 的 Fragment ，通过代码在 tab 切换 Fragment 时触发页面浏览事件：

 //通过代码触发 Fragment 页面浏览事件
SensorsDataAPI.sharedInstance().trackViewScreen(appFragment);

3. 通过代码 track 浏览页面事件($AppViewScreen)

public void trackViewScreen(String url, JSONObject properties)

此方法用于 Activity 内 切换页面的时候调用，用于记录 $AppViewScreen 事件.

url ：页面的 url， 记录到 $url 字段中(如果不需要此属性，可以传 null )。

properties ：页面的属性。

注意：为保证记录到的 $AppViewScreen 事件和 Auto Track 采集的一致，页面的属性中 需要传入 $title（页面的title） 、$screen_name (页面的名称，即 包名.类名)字段。

  try {
       JSONObject properties = new JSONObject();
       //记录打开 首页Fragment 的 $AppViewSceen 事件。
       properties.put("$title", "首页")
                 .put("$screen_name", "cn.sensorsdata.demo.HomeFragment");
       SensorsDataAPI.sharedInstance().trackViewScreen(null, properties);
  } catch (Exception e) {
       e.printStackTrace();
  }

从 v1.7.9 开始也可以使用下面方法来触发浏览页面事件：

//触发 Activity 的浏览页面事件
public void trackViewScreen(Activity activity)
//触发 Fragment 的浏览页面事件
public void trackViewScreen(Fragment fragment)

4. AlertDialog

对于 AlertDialog（ android.app.AlertDialog、android.support.v7.app.AlertDialog），需要给 Dialog 设置 OwnerActivity，才能采集到 AlertDialog 所属页面 (Activity) 的信息（属性：$screen_name、$title）。

如果是调用dialog.show()显示dialog：

dialog.setOwnerActivity(activity);

如果是调用builder.show()显示dialog

builder.show().setOwnerActivity(activity);

5. 忽略某个页面或某些页面的事件

如果想忽略某个或某些页面的事件（$AppClick、$AppViewScreen），可以使用如下方法：

//忽略单个页面
SensorsDataAPI.sharedInstance().ignoreAutoTrackActivity(MainActivity.class);

//忽略多个页面
List<Class<?>> classList = new ArrayList<>();
classList.add(MainActivity.class);
SensorsDataAPI.sharedInstance().ignoreAutoTrackActivities(classList);

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

如果想忽略某个控件类型及其子类控件的点击事件($AppClick)，可以使用如下方法：

SensorsDataAPI.sharedInstance().ignoreViewType(Class viewType);

viewType 可以是 Android 常见的控件类型及自定义类型，如：CheckBox、RadioButton、Button、SwitchCompat、Spinner、TextView、ImageView、ImageButton、SeekBar、RatingBar、RadioGroup、ExpandableListView、Dialog、ListView、GridView、TabHost 等。

7. 忽略某个View的点击事件

如果要忽略某个 view 的点击事件（$AppClick），比如某个 view 的点击事件对整个业务分析完全没有任何作用，或者自定义的密码输入键盘等，可以使用如下的方法忽略点击事件：

SensorsDataAPI.sharedInstance().ignoreView(View view);

8. 设置元素ID

为了有效的区分页面元素 (view)，SDK 默认使用 android:id 的值作为点击事件的 $element_id 属性，如果元素没有设置 android:id 属性，或者设置的不符合要求，可以使用如下方法设置元素 ID：

SensorsDataAPI.sharedInstance().setViewID(View view, String viewID);

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

SensorsDataAPI.sharedInstance().setViewID(android.app.Dialog view, String viewID);

或

SensorsDataAPI.sharedInstance().setViewID(android.support.v7.app.AlertDialog view, String viewID);

注意 setViewID 的优先级高于 android:id。

9. 自定义元素属性

点击 view 时，如果在发送 $AppClick 事件时还需要添加其它属性，可以通过如下方法进行扩展：

SensorsDataAPI.sharedInstance(context).setViewProperties(View view, JSONObject properties);

当点击 view 后，发送 $AppClick 事件时，会把 properties 的内容带上。

注意

• 对于 ExpandableListView，可以通过 setViewProperties 方法对 item 所在的 view 设置扩展属性，也可以通过 Adapter 实现 SensorsExpandableListViewItemTrackProperties 接口来扩展属性。

package com.sensorsdata.analytics.android.sdk;

public interface SensorsExpandableListViewItemTrackProperties {
    /**
     * 点击 groupPosition、childPosition 处 item 的扩展属性
     * @param groupPosition
     * @param childPosition
     * @return
     * @throws JSONException
     */
    JSONObject getSensorsChildItemTrackProperties(int groupPosition, int childPosition) throws JSONException;

    /**
     * 点击 groupPosition 处 item 的扩展属性
     * @param groupPosition
     * @return
     * @throws JSONException
     */
    JSONObject getSensorsGroupItemTrackProperties(int groupPosition) throws JSONException;
}

• 对于 ListView、GridView，可以通过 setViewProperties 方法对 item 所在的 view 设置扩展属性，也可以通过 Adapter 实现 SensorsAdapterViewItemTrackProperties 接口来扩展属性。

package com.sensorsdata.analytics.android.sdk;

public interface SensorsAdapterViewItemTrackProperties {
    /**
     * 点击 position 处 item 的扩展属性
     * @param position
     * @return
     * @throws JSONException
     */
    JSONObject getSensorsItemTrackProperties(int position) throws JSONException;
}

10. 注解 @SensorsDataIgnoreTrackAppViewScreen

忽略某个 Activity 或 Fragment 的页面浏览事件($AppViewScreen)

例如：忽略 DemoActivity 的页面浏览事件

//忽略 DemoActivity 的页面浏览事件
@SensorsDataIgnoreTrackAppViewScreen
public class DemoActivity extends AppCompatActivity {

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_demo);
    }
}

11. 注解 @SensorsDataTrackViewOnClick

如果你是使用 android:onclick 属性给 View 添加点击处理函数，此时你可以在处理函数上使用 @SensorsDataTrackViewOnClick 注解，在该函数执行时，SDK 会发 $AppClick 事件。

例如：

XML:

<Button
    android:id="@+id/button"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:text="普通Button"
    android:onClick="buttonOnClick"
    android:textAllCaps="false" />

处理函数：

import com.sensorsdata.analytics.android.sdk.SensorsDataTrackViewOnClick;

@SensorsDataTrackViewOnClick
public void buttonOnClick(View v) {

}

12. 注解 @SensorsDataTrackEvent

对于一些简单的场景，比如当某一个方法执行时就 track 一个事件，可以在该方法上使用 @SensorsDataTrackEvent 注解。当该方法执行时，SDK 会 track 一个指定的事件。

例如：

@SensorsDataTrackEvent(eventName = "someEventName", properties = "{\"provider\":\"神策数据\",\"number\":100,\"isLogin\":true}")
public void someMethod() {

}

这样，每当函数 someMethod() 执行时，SDK 就会 track 一个事件，其中事件名称为 someEventName，属性有:

"provider":"神策数据",
"number":100,
"isLogin":true

13. 开启 React Native 页面控件的自动采集（$AppClick）

1.7.14 及以后的版本， 支持在初始化 SDK 之后，通过 enableReactNativeAutoTrack() 方法开启 RN 页面控件点击事件的自动采集。

//初始化SDK后，开启 RN 页面控件点击事件的自动采集
SensorsDataAPI.sharedInstance().enableReactNativeAutoTrack();

开启 RN 页面控件点击事件的自动采集，必须使用这个 classpath 'com.sensorsdata.analytics.android:android-gradle-plugin:1.2.2' 版本的插件。(注意：不是plugin2:x.x.x)

14. TODO

• EditText
• Banner