集成曝光
注意
- 需联系神策售后获取支持曝光埋点的 har 包，且 SDK 版本需要 >= 0.7.0
- HarmonyOS 版本 >= 5.0.0，即要求 API version >= 12
曝光埋点在鸿蒙端 SDK 是以插件的方式来开发的，相关集成代码可参考如下：
import sensors, { SAExposure } from '@sensorsdata/analytics'
// 使用曝光插件，传入曝光的全局配置
sensors.use(SAExposure({
areaRate:1,
repeated: true,
updateInterval: 500
}))
// 初始化埋点 SDK
sensors.init({
server_url: '${数据上报地址}',
context: this.context,
show_log: true,
})
使用
曝光条件配置参数
SDK 提供 SAExposureConfig 来设置曝光条件，具体参数说明如下：
| 参数 |
类型 |
描述 |
| areaRate |
number |
曝光的可见比例，有效值范围 0 ~ 1，
- 默认值为 0，代表元素只要露出就满足可见比例条件
- 最大值为 1，代表元素需要完全露出才可满足可见比例条件
|
| updateInterval |
number |
计算面积比例的时间间隔，单位为毫秒
- 默认值为 500，最小值为 100，不建议设置过小，会影响性能
|
| repeated |
boolean |
是否允许采集重复曝光
|
曝光条件设置
初始化一个曝光配置
const exposureConfig: SAExposureConfig = new SAExposureConfig(1, true, 500)
SDK 提供全局设置曝光配置，即在集成曝光插件的时候传入的配置，同时 SDK 也提供了对某个组件单独设置
const exposureData: SAExposureData = new SAExposureData('HelloExposure',exposureConfig)
exposure.addExposureNode('testButton', context, exposureData)
注意：
- 全局的曝光设置有一个默认值，及 areaRate = 0，updateInterval = 500，repeated = false
- 标记视图组件时，如果不传入配置项，则会使用全局曝光配置
- 标记视图组件时，如果传入配置项，则会使用传入的自定义配置
- 不同的视图组件可以使用不同的曝光配置，曝光配置和标记视图时传入的配置对应
曝光组件标记
组件标记相关类和接口说明
SDK 提供 SAExposureData 类和接口 addExposureNode 来标记某个组件的曝光，相关的说明如下：
SAExposureData
| 参数 |
类型 |
描述 |
| event |
string |
组件曝光时触发的事件名 |
| properties |
EventProps |
可选值，组件曝光时触发的事件的自定义属性，请参考神策事件属性格式：数据格式 |
| exposureConfig |
SAExposureConfig |
曝光条件配置，可选值，不传入则使用全局配置 |
addExposureNode
| 参数 |
类型 |
描述 |
| nodeId |
string |
需要被曝光的元素对象 |
| context |
UIContext |
曝光组件对应的 UIContext |
| exposureData |
SAExposureData |
标记组件时传入的曝光数据，包含事件名、属性、曝光条件配置等 |
组件标记
以 Button 组件为例，添加曝光代码如下：
@Component
struct NavigationTest {
build() {
...
//对曝光组件要设置 id
Button('HelloWorld').id('exposure_button')
}
onDidBuild(): void {
//获取 UIContext
let context = this.getUIContext()
if (!context) {
return
}
//获取神策曝光插件
const exposure: SAExposurePlugin = sensors.exposure() as SAExposurePlugin
//曝光相关配置
const exposureData = new SAExposureData('HelloExposure', new SAExposureConfig(1, true),{'name': 'jack'})
//添加曝光组件
exposure.addExposureNode('exposure_button', context, exposureData)
}
}
注意：
- 必须对需要曝光的组件设置唯一的 id，可通过 id('唯一的 id') 来设置
- 必须传入该组件对应的 UIContext
- 添加曝光组件时，必须传入该组件通过 id('xx') 接口设置的 id，必须一一对应，否则无法正确曝光
- 添加曝光组件需等组件 build 完成后才可以添加，一般建议在 onDidBuild 中去添加需要曝光的组件，添加过早无法正确曝光
移除组件标记
当我们不想采集某个组件的曝光时，可以使用 SDK 提供的移除标记接口 removeExposureNodeById，接口说明如下：
| 参数 |
类型 |
描述 |
| nodeId |
string |
需要移除曝光的组件的 id |
示例代码如下：
exposure.removeExposureNodeById('需要移除曝光的组件 id')
