集成
在使用插件前,请务必参考 插件使用方式
ES Module 集成方式
import Exposure from '/dist/wechat/plugin/exposure/index.esm';
var exposure = sensors.usePlugin(Exposure, {
class_tags:['sensors-exposure-track'],
area_rate: 0,
stay_duration: 2,
repeated: true
});
版本要求
需 微信小程序 SDK v1.18.6 及以上版本
使用
在使用神策曝光功能之前,建议先了解下神策曝光的相关介绍:曝光采集
初始化曝光插件及配置
import Exposure from '/dist/wechat/plugin/exposure/index.esm';
var exposure = sensors.usePlugin(Exposure, {
class_tags:['sensors-exposure-track'],
area_rate: 0,
stay_duration: 2,
repeated: true
});
配置参数
参数 | 类型 | 默认 | 描述 |
---|---|---|---|
class_tags | Array<String> | ['sensors-exposure-track'] | 元素 class 属性中设置的曝光标记 |
area_rate | Number | 0 | 曝光的可见比例,有效值范围 0~1,
|
stay_duration | Number | 0 | 有效停留时长,单位为秒
|
repeated | Boolean | true | 是否允许采集重复曝光
|
framework | Object | 无 | 在 taro 中设置元素曝光需要设置该属性。且值固定为
微信小程序 SDK v1.19.5及以上版本支持 |
注意:
- 初始化设置的配置,是修改全局的默认配置。
- 标记视图元素时,如果不传入配置项,则会使用全局曝光配置
- 标记视图元素时,如果传入配置项,则会使用传入的自定义配置
- 不同的视图元素标记可以使用不同的曝光配置,曝光配置和标记视图时传入的配置对应
- 使用 API 新增/刷新视图原始标记后,如果传入配置项,则调用 API 后检测到的视图元素使用的是标记视图时传入的自定义配置。
- 使用 API 新增/刷新视图原始标记后,如果不传入配置项,则调用 API 后检测到的视图元素使用的还是上一次标记视图时传入的配置。
- framework 配置。微信小程序 SDK v1.19.5及以上版本支持
配置曝光元素
元素属性统一添加曝光配置
通过添加元素曝光 `class` 标记,并设置元素属性 `data-sensors-exposure-option` 统一进行曝光事件采集配置。
// index.wxml
<view class="sensors-exposure-track" data-sensors-exposure-option="{{option}}"></view>
// Page.js
Page({
data: {
option: {
event_name: "exposure_name",
config: {
area_rate: 0,
stay_duration: 0,
repeated: true
},
properties: {
propA: "valueA"
}
}
}
})
配置参数
参数 | 必填 | 描述 |
---|---|---|
class="sensors-exposure-track" | 是 | 元素 class 属性中设置的曝光标记(必须添加标记) |
data-sensors-exposure-option | 是 | 统一设置当前元素的曝光配置 config 及自定义属性 properties。 |
option 配置参数:
参数 | 必填 | 描述 |
---|---|---|
event_name | 是 | 设置曝光事件名称(必须设置) |
config | 否 | 曝光元素配置。同初始化曝光配置。
|
properties | 否 | 自定义属性。类型: Object。设置该元素曝光事件自定义属性。支持区分大小写及属性值其他类型 |
通过元素配置单独添加曝光参数
通过添加元素曝光 `class` 标记,并单独设置相关元素属性设置曝光事件采集配置。
// index.wxml
<view class="sensors-exposure-track" data-sensors-exposure-event-name="home_top_banner" data-sensors-exposure-config-area_rate="1" data-sensors-exposure-config-stay_duration="2" data-sensors-exposure-config-repeated="true" data-sensors-exposure-property-propA="valueA" data-sensors-exposure-property-propB="valueB"></view>
配置参数
参数 | 必填 | 描述 |
---|---|---|
class="sensors-exposure-track" | 是 | 元素 class 属性中设置的曝光标记 (必须添加标记) |
data-sensors-exposure-event-name | 是 | 设置曝光事件名称(必须设置) |
data-sensors-exposure-config-area_rate | 否 | 设置曝光比例 |
data-sensors-exposure-config-stay_duration | 否 | 设置有效曝光停留时长 |
data-sensors-exposure-config-repeated | 否 | 设置重复曝光 |
data-sensors-exposure-property-* | 否 | 设置该元素曝光事件自定义属性。属性值为 String。无法是其他类型。 |
通过 API 配置曝光参数
exposure.addObserverByClassName('元素 class 标记', {
area_rate: 0.5,
stay_duration: 0,
repeated: true
},{
shouldExpose: function(tag, properties){
// tag 为当前曝光的元素的曝光标记
// properties 为曝光元素的元素信息及该元素的曝光自定义属性
// 触发曝光事件则返回 true
// 不触发曝光事件则返回 false
return true
},
didExpose: function(tag, properties){
// tag 为当前曝光的元素的曝光标记
// properties 为曝光元素的元素信息及该元素的曝光自定义属性
}
})
配置参数
参数 | 必填 | 描述 |
---|---|---|
class_tag | 是 | 元素 class 属性中设置的曝光标记。类型: String |
config | 是 | 曝光元素配置。同初始化曝光配置。
|
listener | 否 | 当前曝光元素触发曝光事件时的监听回调。 微信小程序 SDK v1.19.5及以上版本支持。
|
通过 API 删除曝光标记监听
exposure.removeObserverByClassName('元素 class 标记')
配置参数:
- class_tag: 曝光元素检测标记。类型: String。(必须添加标记)
注意
- 已注册的曝光元素标记
class_tag
,再次注册仅更新之前未注册的元素,已注册的元素不会再次注册,已注册的元素不会因调用注册 API 导致发送曝光事件。- 如未设置元素
ID
,是通过曝光元素event-name
(事件名)与property
(事件属性)区分曝光元素。- 每个曝光元素
event-name
(事件名)或property
(事件属性)或 id (元素 ID) 必须有差异,否则只会曝光查询到的第一个元素。- 微信小程序 SDK 版本必须大于或等于 1.18.6。
- 插件和 SDK 必须在同一个版本中,请勿混合不同版本的 SDK 和插件进行使用。
不同场景添加曝光元素
动态渲染元素添加曝光
// index.wxml
<view class="sensors-exposure-track" wx:for="{{list}}" wx:key="index" data-sensors-exposure-event-name="exposure_{{index}}" data-sensors-exposure-config-stay_duration="2" data-sensors-exposure-config-repeated="true" data-sensors-exposure-property-propA="{{item.name}}" data-sensors-exposure-property-propB="valueB">
{{index}}: {{item.name}}
</view>
// index.js
const exposure = getApp().globalData.exposure
Page({
data(){
return {
list:[]
}
},
onShow(){
// 模拟延迟渲染列表
setTimeout(()=>{
// 设置列表后,回调中设置添加元素曝光
this.setData({list:[{name:'list1'},{name:'list2'}]},()=>{
exposure.addObserverByClassName('sensors-exposure-track',option); // option 同通过 API 配置曝光参数
})
},3000)
}
})
Commpent 中注册曝光
components/my-component/my-component.wxml
中添加曝光标记及配置。微信小程序 SDK v1.19.5及以上版本支持。
<!--components/my-component/my-component.wxml-->
<view class="sensors-exposure-track" data-sensors-exposure-event-name="component" >
<text>曝光元素</text>
</view>
components/my-component/my-component.js
中的 pageLifetimes.onshow
中通知 SDK 更新曝光元素
// components/my-component/my-component.js
Component({
pageLifetimes: {
// 组件所在页面的生命周期函数
show: function () {
getApp().sensors.modules["Exposure"].addObserverByClassName("sensors-exposure-track", {
area_rate: 0.5,
stay_duration: 0,
repeated: true,
component: this, // 传入当前 Component 的 this 指向
}
);
});
Taro 中注册曝光
app.js
中初始化微信小程序 SDK 及初始化曝光插件。微信小程序 SDK v1.19.5及以上版本支持。
// app.js
import sensors form '/dist/wechat/sensorsdata.esm.js'
import Taro from "@tarojs/taro";
// 仅在微信小程序时生效
if (process.env.TARO_ENV === 'weapp') {
import Exposure from "/dist/wechat/plugin/exposure/index.esm";
sensors.usePlugin(Exposure, {
framework: {
taro: Taro, // 传入 Taro 对象
}
});
}
sensors.init({
name: 'sensors',
server_url: '您的数据接收地址',
show_log: true
});
pages/index/index.vue
需要曝光的页面中添加曝光配置及通知 SDK 更新曝光元素
// pages/index/index.vue
import Taro from "@tarojs/taro";
export default {
onShow() {
// 需要在 Taro 渲染完毕后,通知 SDK 更新曝光元素。
Taro.nextTick(() => {
app.sensors.modules.Exposure.addObserverByClassName("sensors-exposure-track");
});
},
setup() {
return () => {
return (
<View
className="sensors-exposure-track"
data-sensors-exposure-event-name="exposure_ele"
>
<Text>曝光元素</Text>
</View>
);
};
},
}
uni-app 中注册曝光
main.js
中初始化微信小程序 SDK 及初始化曝光插件。微信小程序 SDK v1.19.5及以上版本支持。
// app.js
import sensors from '神策 uni-app JS SDK 路径/index.js';
// 仅在微信小程序时生效
// #ifdef MP-WEIXIN
import Exposure from "/dist/wechat/plugin/exposure/index.esm";
sensors.instance.usePlugin(Exposure, /** 曝光配置 **/);
// #endif
sensors.init(
//... 相关配置
);
export default {
globalData: {
sensors: sensors
},
onLaunch: function() {
console.log('App Launch')
},
onShow: function() {
console.log('App Show')
},
onHide: function() {
console.log('App Hide')
}
}
pages/index/index.vue
需要曝光的页面中添加曝光配置及通知 SDK 更新曝光元素
// pages/index/index.vue
<template>
<view class="content">
<view class="sensors-exposure-track"data-sensors-exposure-event-name="exposure_ele"> 曝光元素 </button>
</view>
</template>
<script>
var sensors = getApp().globalData.sensors;
export default {
onShow(){
// 仅在微信小程序时生效
// #ifdef MP-WEIXIN
sensors.instance.modules.Exposure.addObserverByClassName("sensors-exposure-track");
// #endif
}
}
</script>