1. 集成

目前 Web/小程序逐步演变为插件化的架构方式。“一切都是插件” 的概念会越发的明显。

在使用插件前，请务必参考插件使用方式

1.1. ES Module 集成方式

import exposure from '/dist/wechat/plugin/exposure/index.es6';
sensors.usePlugin(exposure, {
  class_tags:['sensors-exposure-track'],
  area_rate: 0, 
  stay_duration: 2, 
  repeated: true 
});

JS

版本要求

微信小程序 SDK v1.18.5 及以上版本

2. 使用

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

2.1. 曝光条件配置参数

SDK 提供初始化时，来设置曝光条件，具体参数说明如下：

参数	类型	默认	描述
class_tags	Array<String>	['sensors-exposure-track']	曝光元素检测标记
area_rate	Number	0	曝光的可见比例，有效值范围 0~1，默认值为 0，代表元素只要露出就满足可见比例条件最大值为 1，代表元素需要完全露出才可满足可见比例条件
stay_duration	Number	0	有效停留时长，单位为秒默认值为 0，代表元素只要满足了可见比例，有效停留时长就可满足
repeated	Boolean	true	是否允许采集重复曝光默认值为 true，及允许采集重复曝光

2.2. 曝光条件设置

初始化设置曝光配置

sensors.usePlugin(exposure, {
  class_tags:['sensors-exposure-track'],
  area_rate: 0, 
  stay_duration: 2, 
  repeated: true 
});

JS

配置参数：

class_tags: 曝光元素检测标记。默认：['sensors-exposure-track']。类型: Array
area_rate：曝光比例。默认：0，值域：0~1。类型：Number
stay_duration: 有效曝光停留时长。默认：0。类型：Number
repeated: 重复曝光。默认：true。类型：Boolean

注意：

初始化设置的配置，是修改全局的默认配置。
标记视图元素时，如果不传入配置项，则会使用全局曝光配置
标记视图元素时，如果传入配置项，则会使用传入的自定义配置
不同的视图元素标记可以使用不同的曝光配置，曝光配置和标记视图时传入的配置对应
使用 API 新增/刷新视图原始标记后，如果传入配置项，则调用 API 后检测到的视图元素使用的是标记视图时传入的自定义配置。
使用 API 新增/刷新视图原始标记后，如果不传入配置项，则调用 API 后检测到的视图元素使用的还是上一次标记视图时传入的配置。

2.3. 曝光元素标记

2.3.1. 通过元素配置统一添加曝光参数

通过添加元素曝光 `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"
      }
    }
  }
})

XML

配置参数：

sensors-exposure-track 元素 class 属性设置曝光标记（必须添加标记）
data-sensors-exposure-option 设置曝光事件配置（必须设置）
- event_name 设置曝光事件名称（必须设置）
- config.area_rate 设置曝光比例
- config.stay_duration 设置有效曝光停留时长
- config.repeated 设置重复曝光
- properties 设置该元素曝光事件自定义属性。支持区分大小写及属性值其他类型。

2.3.2. 通过元素配置单独添加曝光参数

通过添加元素曝光 `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>

XML

配置参数

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。无法是其他类型。

2.3.3. 通过 API 配置曝光参数

exposure.addObserverByClassName('元素 class 标记', {
    area_rate: 0.5,
    stay_duration: 0,
    repeated: true
})

JS

配置参数：

class_tag: 曝光元素检测标记。类型: String。（必须添加标记）
config：该次注册曝光标记的配置
- area_rate：曝光比例。默认：0，值域：0~1。类型：Number
- stay_duration: 有效曝光停留时长。默认：0。类型：Number
- repeated: 重复曝光。默认：true。类型：Boolean

2.3.4. 动态渲染元素添加曝光

// 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)
    }
})

XML

2.3.5. 通过 API 删除曝光标记监听

exposure.removeObserverByClassName('元素 class 标记')

JS

配置参数：

class_tag: 曝光元素检测标记。类型: String。（必须添加标记）

注意

已注册的曝光元素标记 class_tag，再次注册仅更新之前未注册的元素，已注册的元素不会再次注册，已注册的元素不会因调用注册 API 导致发送曝光事件。
每个曝光元素 event-name （事件名）或 property（事件属性）必须有差异，否则在 repeated 为 false 时，只会曝光查询到的第一个参数。
如未设置元素 ID，是通过曝光元素 event-name （事件名）与 property（事件属性）区分曝光元素。
微信小程序 SDK 版本必须大于或等于 1.18.5。
插件和 SDK 必须在同一个版本中，请勿混合不同版本的 SDK 和插件进行使用。