SDK 集成
请参考集成文档(Android)。
版本要求
Android SDK v6.5.2 及以上版本
使用
在使用神策曝光功能之前,建议先了解下神策曝光的相关介绍:曝光采集
曝光条件设置
示例曝光配置:
SAExposureConfig 详细参数如下:
参数 | 类型 | 描述 |
---|---|---|
areaRate | float | 曝光可见比例,默认值 0.0f,曝光范围是 0~1f;
|
stayDuration | double | 有效停留时长,默认值是 0.0,时长单位是秒;只有当曝光元素满足有效停留时长才会触发曝光埋点事件。 |
repeated | boolean | 重复曝光,默认值是 true;
|
注意:只有当曝光配置 areaRate、stayDuration、repeated 三者都满足时才能触发曝光埋点事件。
示例代码
SDK 提供全局设置曝光配置
示例代码
SDK 对某个视图元素单独设置曝光配置
示例代码
SAExposureData 详细参数如下:
参数 | 类型 | 描述 |
---|---|---|
event | String | 曝光事件名称 |
properties | JSONObject | 曝光事件属性 |
exposureConfig | SAExposureConfig | 曝光配置 |
addExposureView 详细参数如下:
参数 | 类型 | 描述 |
---|---|---|
view | View | 曝光元素(view) |
exposureData | SAExposureData | 曝光数据 |
注意:
- 全局的曝光设置有一个默认值,即 areaRate = 0.0f,stayDuration = 0,repeated = true
- 标记视图元素时,如果不传入配置项,则会使用全局曝光配置
- 标记视图元素时,如果传入配置项,则会使用传入的自定义配置
- 不同的视图元素可以使用不同的曝光配置,曝光配置和标记视图时传入的配置对应
曝光元素标记
普通视图元素标记
示例代码
列表元素标记
当列表使用曝光的时候,由于列表元素在绘制过程中会复用,因此针对列表复用场景需要对列表元素进行唯一标识 exposureIdentifier 设置,一般可以通过 SAExposureData 进行设置,具体如下:
示例代码
SAExposureData 详细参数如下:
参数 | 类型 | 描述 |
---|---|---|
event | String | 曝光事件名称 |
properties | JSONObject | 曝光事件属性 |
exposureIdentifier | String | 元素(view)的唯一标识值 |
exposureConfig | SAExposureConfig | 曝光配置 |
注意:当元素(view)设置了唯一标识(exposureIdentifier),则通过唯一标识来进行曝光元素识别;因此不建议同一个页面不同元素设置相同唯一标识,只建议列表使用的时候进行元素唯一标识设置以避免列表复用导致的采集不准。
下面以 RecyclerView 为例,元素唯一标识一般用列表的位置进行标记:
标记所有行
示例代码
标记单个行
当针对列表中的某行或者某列进行标记而不是所有的行或列进行标记的时候需要通过 setExposureIdentifier 进行标记所有的元素,然后再通过 addExposureView 进行标记需要曝光的行或列的元素。
示例代码
setExposureIdentifier 详细参数如下:
参数 | 类型 | 描述 |
---|---|---|
view | View | 曝光元素(view) |
exposureIdentifier | String | 曝光元素(view)唯一标识符 |
示例代码
注意:如果标记某一行或某一列时,不使用曝光标识 setExposureIdentifier 进行设置,会导致曝光数据采集不准,单纯靠 position 是无法准确判定当前 position 是否是想要标记的元素;并且 setExposureIdentifier 和 addExposureView 进行标记的同一个元素 view 的唯一标识需要相同。
移除元素标记
当我们不想采集某个元素的曝光时,可以使用 SDK 提供的移除标记接口 removeExposureView,有如下两个接口:
示例代码
removeExposureView 详细参数如下:
参数 | 类型 | 描述 |
---|---|---|
view | View | 曝光元素(view) |
exposureIdentifier | String | 曝光元素(view)唯一标识符 |
注意:当使用 removeExposureView 携带 exposureIdentifier 参数的时候,必须是 view 和 exposureIdentifier 两者同加入到曝光列表的信息完全相同才能移除。
曝光回调
SDK 从 6.6.9 版本提供了一个曝光监听的协议接口, 可通过 SAExposureData 中的 exposureListener 来设置,接口说明如下:
SAExposureListener 说明如下:
其中参数说明如下:
参数 | 类型 | 描述 |
---|---|---|
view | View | 曝光的元素 |
data | SAExposureData | 标记元素时传入的曝光数据,包含事件名、属性、曝光条件配置等 |
注意:shouldExposure 和 didExposure 回调都在主线程执行,禁止做耗时操作。
代码使用示例:
更新某个元素的曝光属性
SDK 从 6.6.9 版本提供了一个曝光监听的协议接口, 可通过 updateExposureProperties 更改曝光元素的属性。
参数 | 类型 | 描述 |
---|---|---|
view | View | 曝光的元素 |
properties | JSONObject | 需要更新的元素属性,注意与添加曝光元素时设置的同名属性为覆盖关系。例如 addExposureView 传入的 properties 是 {"key1": "value1"},如果在 updateExposureProperties 时 {"key2": "value2"},最终上报的是{"key1": "value1","key2": "value2"}。 |