1. 神策分析 Android SDK AutoTrack 使用说明

1.1. 配置

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

对于 App 中的核心页面(Activity、Fragment),我们提供了一个 接口 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 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");
		//返回 $title,会覆盖默认 $title 的值,最终浏览事件的 $title 以此处传入的为准
		jsonObject.put("$title", "HomeFragment");
		return jsonObject;
	}
}
JAVA

1.1.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

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

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

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

1.1.4. 忽略部分 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

1.1.5. 通过代码 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

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

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

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

1.1.7. 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

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

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

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

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

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

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

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

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

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

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

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

1.1.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

1.1.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

1.1.13. 注解 @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);
	}
}
JAVA

1.1.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

1.1.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

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

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

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

1.1.17. TODO

  •  EditText
  •  Banner