曝光采集（Android）

SDK 集成

版本要求

Android SDK v6.5.2 及以上版本

使用

在使用神策曝光功能之前，建议先了解下神策曝光的相关介绍：曝光采集

曝光条件设置

示例曝光配置：

SAExposureConfig exposureConfig = new SAExposureConfig(areaRate, stayDuration, repeated);

SAExposureConfig 详细参数如下：

参数

类型

描述

areaRate

float

曝光可见比例，默认值 0.0f，曝光范围是 0~1f；

当为 0.0f 时为元素曝光任意像素可见即可触发曝光埋点事件
当为 1.0f 时为元素曝光完全可见才能触发曝光埋点事件

stayDuration

double

有效停留时长，默认值是 0.0，时长单位是秒；只有当曝光元素满足有效停留时长才会触发曝光埋点事件。

repeated

boolean

重复曝光，默认值是 true；

当为 true 时已曝光元素在页面隐藏起来，然后再满足曝光条件显示在页面时可以继续触发曝光埋点事件
当为 false 时已曝光元素在页面隐藏起来，然后再满足曝光条件显示在页面时无法继续触发曝光埋点事件

注意：只有当曝光配置 areaRate、stayDuration、repeated 三者都满足时才能触发曝光埋点事件。

示例代码

//当我们设置元素完全曝光，有效停留时长 1s ，支持重复曝光
SAExposureConfig exposureConfig = new SAExposureConfig(1.0f, 1, true);

CODE

SDK 提供全局设置曝光配置

示例代码

String SA_SERVER_URL = "数据接收地址";
SAConfigOptions configOptions = new SAConfigOptions(SA_SERVER_URL);
// 初始化曝光模块配置
configOptions.setExposureConfig(exposureConfig);

CODE

SDK 对某个视图元素单独设置曝光配置

示例代码

View view = findViewById(R.id.resourceID);
String event = "曝光事件名称";
JSONObject properties = new JSONObject();
try {
    properties.put("曝光事件属性 key", "曝光事件属性 value");
} catch (JSONException e) {
    e.printStackTrace();
}
SAExposureConfig exposureConfig = new SAExposureConfig(1.0f, 1, true);
SAExposureData exposureData = new SAExposureData(event, properties, exposureConfig);
SensorsDataAPI.sharedInstance().addExposureView(view, exposureData); //标记视图元素

CODE

SAExposureData 详细参数如下：

参数	类型	描述
event	String	曝光事件名称
properties	JSONObject	曝光事件属性
exposureConfig	SAExposureConfig	曝光配置

addExposureView 详细参数如下：

参数	类型	描述
view	View	曝光元素（view）
exposureData	SAExposureData	曝光数据

注意：

全局的曝光设置有一个默认值，即 areaRate = 0.0f，stayDuration = 0，repeated = true
标记视图元素时，如果不传入配置项，则会使用全局曝光配置
标记视图元素时，如果传入配置项，则会使用传入的自定义配置
不同的视图元素可以使用不同的曝光配置，曝光配置和标记视图时传入的配置对应

曝光元素标记

普通视图元素标记

示例代码

View view = findViewById(R.id.resourceID);
String event = "曝光事件名称";
JSONObject properties = new JSONObject();
try {
    properties.put("曝光事件属性 key", "曝光事件属性 value");
} catch (JSONException e) {
    e.printStackTrace();
}
SAExposureConfig exposureConfig = new SAExposureConfig(1.0f, 1, true);
SAExposureData exposureData = new SAExposureData(event, properties, exposureConfig);
SensorsDataAPI.sharedInstance().addExposureView(view, exposureData);

CODE

列表元素标记

当列表使用曝光的时候，由于列表元素在绘制过程中会复用，因此针对列表复用场景需要对列表元素进行唯一标识 exposureIdentifier 设置，一般可以通过 SAExposureData 进行设置，具体如下：

示例代码

SAExposureData exposureData = new SAExposureData("exposureName", null, "11",exposureConfig);

CODE

SAExposureData 详细参数如下：

参数	类型	描述
event	String	曝光事件名称
properties	JSONObject	曝光事件属性
exposureIdentifier	String	元素（view）的唯一标识值
exposureConfig	SAExposureConfig	曝光配置

注意：当元素（view）设置了唯一标识（exposureIdentifier），则通过唯一标识来进行曝光元素识别；因此不建议同一个页面不同元素设置相同唯一标识，只建议列表使用的时候进行元素唯一标识设置以避免列表复用导致的采集不准。

下面以 RecyclerView 为例，元素唯一标识一般用列表的位置进行标记：

标记所有行

示例代码

public void onBindViewHolder(@NonNull ViewHolder holder, final int position) {
     View view = holder.xxxx; 
     SAExposureConfig exposureConfig = new SAExposureConfig(1.0f, 1, true);
     SAExposureData exposureData = new SAExposureData("exposureName", null, "曝光标识", exposureConfig);////曝光标识用于区分列表元素的特殊场景，比如列表元素复用、列表元素位置变更（刷新、删除、添加等），建议客户使用列表元素的数据源中的唯一标识来处理      
     SensorsDataAPI.sharedInstance().addExposureView(view, exposureData);//添加曝光元素（view）到曝光列表 
}

CODE

标记单个行

当针对列表中的某行或者某列进行标记而不是所有的行或列进行标记的时候需要通过 setExposureIdentifier 进行标记所有的元素，然后再通过 addExposureView 进行标记需要曝光的行或列的元素。

示例代码

//进行标记所有的元素曝光标识，用于区分列表元素的特殊场景，比如列表元素复用、列表元素位置变更（刷新、删除、添加等），建议客户使用列表元素的数据源中的唯一标识来处理 
SensorsDataAPI.sharedInstance().setExposureIdentifier(view, "曝光标识");

CODE

setExposureIdentifier 详细参数如下：

参数	类型	描述
view	View	曝光元素（view）
exposureIdentifier	String	曝光元素（view）唯一标识符

示例代码

public void onBindViewHolder(@NonNull ViewHolder holder, final int position) {
    View view = holder.xxxx;
    SensorsDataAPI.sharedInstance().setExposureIdentifier(view, String.valueOf(position));//曝光标识用于区分列表元素的特殊场景，比如列表元素复用、列表元素位置变更（刷新、删除、添加等），建议客户使用列表元素的位置作为唯一标识来处理
    //只采集列表 position 为 1 的曝光元素的曝光事件
	if(position==1){
        SAExposureConfig exposureConfig = new SAExposureConfig(1.0f, 1, true);
        SAExposureData exposureData = new SAExposureData("exposureName", null, "曝光标识",exposureConfig);//此处的曝光标识，建议客户使用列表元素的数据源中的唯一标识来处理     SensorsDataAPI.sharedInstance().addExposureView(view, exposureData);//添加曝光元素（view）到曝光列表
    }
}

CODE

注意：如果标记某一行或某一列时，不使用曝光标识 setExposureIdentifier 进行设置，会导致曝光数据采集不准，单纯靠 position 是无法准确判定当前 position 是否是想要标记的元素；并且 setExposureIdentifier 和 addExposureView 进行标记的同一个元素 view 的唯一标识需要相同。

移除元素标记

当我们不想采集某个元素的曝光时，可以使用 SDK 提供的移除标记接口 removeExposureView，有如下两个接口：

示例代码

//方法一：
View view = findViewById(R.id.resourceID);
SensorsDataAPI.sharedInstance().removeExposureView(view);

//方法二：
View view = findViewById(R.id.resourceID);
SensorsDataAPI.sharedInstance().removeExposureView(view,"aaa");

CODE

removeExposureView 详细参数如下：

参数	类型	描述
view	View	曝光元素（view）
exposureIdentifier	String	曝光元素（view）唯一标识符

注意：当使用 removeExposureView 携带 exposureIdentifier 参数的时候，必须是 view 和 exposureIdentifier 两者同加入到曝光列表的信息完全相同才能移除。

曝光回调

SDK 从 6.6.9 版本提供了一个曝光监听的协议接口，可通过 SAExposureData 中的 exposureListener 来设置，接口说明如下：

saExposureData.setExposureListener(SAExposureListener saExposureListener)

SAExposureListener 说明如下：

public interface SAExposureListener {
    /**
     * 返回对应 View 是否曝光
     *
     * @param view View
     * @param exposureData View 对应数据
     * @return true：曝光，false：不曝光
     */
    boolean shouldExposure(View view, SAExposureData exposureData);
 
    /**
     * 曝光完成回调
     *
     * @param view View
     * @param exposureData 曝光数据
     */
    void didExposure(View view, SAExposureData exposureData);
}

其中参数说明如下：

参数	类型	描述
view	View	曝光的元素
data	SAExposureData	标记元素时传入的曝光数据，包含事件名、属性、曝光条件配置等

注意：shouldExposure 和 didExposure 回调都在主线程执行，禁止做耗时操作。

代码使用示例：

SAExposureData exposureData = new SAExposureData("expose");
exposureData.setExposureListener(new SAExposureListener() {
	@Override
	public boolean shouldExposure(View view, SAExposureData exposureData) {
		//可以根据实际业务来返回 true 或者 false，这里影响当前曝光监听者的所有曝光事件，需谨慎使用
		if (不需要曝光的条件) {
			return false;
		}
		return true;
	}

	@Override
	public void didExposure(View view, SAExposureData exposureData) {
		//可以根据实际业务需求，在触发曝光后，进行一些业务操作
	}
});
SensorsDataAPI.sharedInstance().addExposureView(view, exposureData);

更新某个元素的曝光属性

SDK 从 6.6.9 版本提供了一个曝光监听的协议接口，可通过 updateExposureProperties 更改曝光元素的属性。

SensorsDataAPI.sharedInstance().updateExposureProperties(view, properties);

参数	类型	描述
view	View	曝光的元素
properties	JSONObject	需要更新的元素属性，注意与添加曝光元素时设置的同名属性为覆盖关系。例如 addExposureView 传入的 properties 是 {"key1": "value1"}，如果在 updateExposureProperties 时 {"key2": "value2"}，最终上报的是{"key1": "value1"，"key2": "value2"}。