1. 全埋点采集策略

SDK 可以自动采集一些用户行为,如 App 启动、退出、浏览页面、控件点击等。可以通过 SAConfigOptions 对象打开自动采集:

SAConfigOptions saConfigOptions = new SAConfigOptions(SA_SERVER_URL);
//在初始化时,利用 SAConfigOptions 对象开启全埋点
saConfigOptions.setAutoTrackEventType(SensorsAnalyticsAutoTrackEventType.APP_CLICK|
        SensorsAnalyticsAutoTrackEventType.APP_START|
        SensorsAnalyticsAutoTrackEventType.APP_END|
        SensorsAnalyticsAutoTrackEventType.APP_VIEW_SCREEN);

//初始化神策对象,需要在主线程初始化 SDK
SensorsDataAPI.startWithConfigOptions(this, saConfigOptions);
JAVA

3.1.0 及之前的版本,SDK 开启全埋点方式:

 查看示例
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();
}
JAVA

1.1. $AppStart (App 启动) 事件

App 启动且符合 session 机制 时,会自动记录 $AppStart 事件,事件包含以下属性:

字段名称类型显示名说明版本
$is_first_timeBOOL是否首次访问App 安装后是否首次启动
$resume_from_backgroundBOOL是否从后台唤醒App 是否是从后台恢复
$title字符串页面标题Activity 的标题(仅 Android 端有)
$screen_name字符串页面名称Activity 的包名.类名(仅 Android 端有)

注意:在 2.0.3 及以上的版本中,$AppStart 的计算规则默认为 30 秒的 session 机制。

1.2. $AppEnd (App 退出)

App 进入后台且符合 session 机制 时,会自动记录 $AppEnd 事件,事件包含以下属性:

字段名称类型显示名说明版本
$event_duration数值事件时长本次 App 启动的使用时长(单位为秒,此字段虽没加 $ 符,也是预置字段)
$title字符串页面标题Activity 的标题(仅 Android 端有)
$screen_name字符串页面名称Activity 的包名.类名(仅 Android 端有)

1.3. $AppViewScreen (App 浏览页面) 事件

App 浏览页面时(切换 Activity),会自动记录 $AppViewScreen 事件,事件包含以下属性:

字段名称类型显示名说明版本
$title字符串页面标题Activity 的标题
$screen_name字符串页面名称Activity 的包名.类名

备注:$title - String 类型,表示 Activity 的标题(1.6.31 及以后版本支持该属性)。Android SDK 按照如下逻辑读取 title 属性:首先读取 activity.getTitle(),如果使用 actionBar,并且 actionBar.getTitle() 不为空,则 actionBar.getTitle() 覆盖 activity.getTitle(),如果以上两步都没有读到 title,则获取 activity 的 android:label 属性。

1.4. $AppClick (App 元素点击) 事件

点击控件时,会发送 $AppClick 事件,包含点击的相应控件的基本信息,事件包含以下属性:

字段名称类型显示名说明版本
$element_id字符串元素 ID控件的 ID
$element_type字符串元素类型控件的类型,例如 Button
$element_content字符串元素内容控件的内容
$title字符串页面标题Activity 的标题
$screen_name字符串页面名称Activity 的包名.类名
$element_position字符串元素位置元素被点击时所处的位置

注意:只有控件本身有 position 时才有 $element_position 字段,例如 ListViewitem。另外,控件本身有 idtext 属性时,对应的 App 元素点击事件才有 $element_id$element_content 属性。

2. 全埋点使用配置说明

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

对于 App 中的核心页面(ActivityFragment),我们提供了一个 接口 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;
}
JAVA

当用户实现该接口时,SDK 会将 getTrackProperties 返回的属性(JSONObject 类型)加入 $AppViewScreen 事件的属性中,作为用户访问该页面时的事件属性;SDK 会将 getScreenUrl 返回的字符串作为页面的 Url Scheme,记录在 $AppViewScreen 事件的 $url 属性中,并且当用户切换页面时,将前一个页面中的 Url Scheme 作为当前页面的 $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");
		//返回 $title,会覆盖默认 $title 的值,最终浏览事件的 $title 以此处传入的为准
		jsonObject.put("$title", "HomeFragment");
		return jsonObject;
	}
}
JAVA

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

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

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

开启了 Fragment 浏览页面的自动采集,可以通过 注解 @SensorsDataIgnoreTrackAppViewScreen 忽略 Fragment 所在 Activity 的页面浏览事件;如果某些 Fragment 的页面浏览事件也不想采集,也可以通过此注解来忽略掉。

如果不想使用自动采集的 Fragment 浏览页面,可以通过代码埋点在 tab 切换 Fragment 时触发页面浏览事件:

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

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

通过 enableAutoTrackFragment 方法,指定只采集某些 Fragment 页面的信息

//初始化 SDK 之后,开启自动采集 Fragment 页面浏览事件
SensorsDataAPI.sharedInstance().trackFragmentAppViewScreen();
//只采集 HomeFragment 页面的浏览事件
SensorsDataAPI.sharedInstance().enableAutoTrackFragment(HomeFragment.class);
JAVA

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

public void trackViewScreen(String url, JSONObject properties)
JAVA

此方法用于 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();
} 
JAVA

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

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

2.5. 通过代码 track 控件点击事件

v3.2.6 开始可以使用以下方法来手动采集 $AppClick 事件,并且该接口不受忽略等条件的限制:

//触发该 View 的点击事件
public void trackViewAppClick(View view)
//触发该 View 的点击事件,并加上自定义属性
public void trackViewAppClick(View view, JSONObject properties)
JAVA

2.6. 忽略部分 Fragment 页面浏览事件的自动采集 ($AppViewScreen)

v3.2.6 开始可以通过如下方法,指定不采集某些 Fragment 页面的信息

//忽略单个 Fragment
SensorsDataAPI.sharedInstance().ignoreAutoTrackFragment(Class<?> fragment);
//忽略多个 Fragment
SensorsDataAPI.sharedInstance().ignoreAutoTrackFragments(List<Class<?>> fragmentList);
JAVA

v3.2.6 开始可以通过如下方法,恢复被忽略的 Fragment 页面浏览事件的自动采集

//忽略单个 Fragment
SensorsDataAPI.sharedInstance().resumeIgnoredAutoTrackFragment(Class<?> fragment);
//忽略多个 Fragment
SensorsDataAPI.sharedInstance().resumeIgnoredAutoTrackFragments(List<Class<?>> fragmentList);
JAVA

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

如果想忽略某个或某些页面的事件($AppClick$AppViewScreen),可以使用如下方法:

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

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

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

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

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

viewType 可以是 Android 常见的控件类型及自定义类型,如:CheckBoxRadioButtonButtonSwitchCompatSpinnerTextView

ImageViewImageButtonSeekBarRatingBarRadioGroup

ExpandableListViewDialogListViewGridViewTabHost 等。

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

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

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

2.10. AlertDialog

对于 AlertDialogandroid.app.AlertDialogandroid.support.v7.app.AlertDialog),需要给 Dialog 设置 OwnerActivity,才能采集到 AlertDialog 所属页面 (Activity) 的信息(属性:$screen_name$title)。

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

dialog.setOwnerActivity(activity);
JAVA

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

builder.show().setOwnerActivity(activity);
JAVA

2.11. 设置元素 ID

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

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

对于 Dialog,可以使用如下方法:

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

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

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

2.12. 自定义元素属性

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

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

当点击 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;
}
JAVA
  • 对于 ListViewGridView,可以通过 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;
}
JAVA

2.13. 注解 @SensorsDataIgnoreTrackAppViewScreen

忽略某个 ActivityFragment 的页面浏览事件 ($AppViewScreen)

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

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

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

2.14. 注解 @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" />
XML

处理函数:

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

@SensorsDataTrackViewOnClick
public void buttonOnClick(View v) {

}
JAVA

2.15. 注解 @SensorsDataTrackEvent

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

注意:被注解的方法一定需要 public 的才可以

例如:

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

}
JAVA

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

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

2.16. 开启 React Native 页面控件的自动采集($AppClick

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

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