1. 集成

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

版本要求

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

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

1.1. 全局初始化曝光插件

// index.wxml 给要曝光的元素的 class 增加标记
<view class="sensors-exposure-track" data-sensors-exposure-event-name="trackView"></view>

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

1.1.1.  初始化全局配置参数说明

参数类型默认描述
class_tagsArray<String>['sensors-exposure-track']通过增加 class 属性，来设置的曝光标记
area_rate

Number

0

曝光的可见比例，有效值范围 0~1，

  • 默认值为 0，代表元素只要露出就满足可见比例条件
  • 最大值为 1，代表元素需要完全露出才可满足可见比例条件

stay_duration

Number

0

有效停留时长，单位为秒

  • 默认值为 0，代表元素只要满足了可见比例，有效停留时长就可满足

repeated

Boolean

true

是否允许采集重复曝光

  • 默认值为 true，及允许采集重复曝光
frameworkObject无

在 taro 中设置元素曝光需要设置该属性。且值固定为

{
  taro:Taro
}
XML

微信小程序 SDK v1.19.5及以上版本支持

1.1.2. 全局配置和单独配置

以上 usePlugin 中传入的初始化的配置，是修改的【全局的默认配置】。在标记视图元素时，如果不传入配置项，则会使用全局曝光配置。标记视图元素时，如果传入配置项，则会使用传入的自定义配置。不同的视图元素标记可以使用不同的曝光配置，曝光配置和标记视图时传入的配置对应。

使用 API 新增/刷新视图原始标记后，如果传入配置项，则调用 API 后检测到的视图元素使用的是标记视图时传入的自定义配置。

使用 API 新增/刷新视图原始标记后，如果不传入配置项，则调用 API 后检测到的视图元素使用的还是上一次标记视图时传入的配置。

1.2. 单独配置各个元素的曝光

1.2.1. 元素属性统一添加曝光配置

上面 JavaScript 代码中，配置了需要在 `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

1.2.1.1. 配置参数

参数必填描述
class="sensors-exposure-track"是元素 class 属性中设置的曝光标记（必须添加标记）

data-sensors-exposure-option

是

统一设置当前元素的曝光配置 config 及自定义属性 properties。

1.2.1.2. option 配置参数:

参数必填描述

event_name

是

设置曝光事件名称（必须设置）

config

否

曝光元素配置。同初始化曝光配置。

  • area_rate: 曝光比例。默认: 0，值域: 0~1。类型：Number
  • stay_duration: 有效曝光停留时长。 默认: 0。类型：Number
  • repeated: 重复曝光。 默认: true。类型: Boolean
properties否自定义属性。类型: Object。设置该元素曝光事件自定义属性。支持区分大小写及属性值其他类型


1.2.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

1.2.2.1. 配置参数

参数必填描述
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。无法是其他类型。

注意：这里 dataset 取到的 * 的属性名，不支持大小写，定义的大写属性也都会被转换成小写


2. 通过 API 配置曝光参数

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

2.1.1.1. 配置参数

参数必填描述

class_tag

是

元素 class 属性中设置的曝光标记。类型: String

config

是

曝光元素配置。同初始化曝光配置。

  • area_rate: 曝光比例。默认: 0，值域: 0~1。类型：Number
  • stay_duration: 有效曝光停留时长。 默认: 0。类型：Number
  • repeated: 重复曝光。 默认: true。类型: Boolean
  • component: Component 的 this 指向。 默认：无。类型：Object。
listener否

当前曝光元素触发曝光事件时的监听回调。

微信小程序 SDK v1.19.5及以上版本支持。

  • shouldExpose: 是否触发曝光事件回调。类型: function
  • didExpose: 已触发曝光回调。类型: function

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

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

配置参数：

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


注意

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

4. 微信 Component 支持 

以上功能只针对微信小程序标准版本。可以参考微信小程序组件的方式来支持。

4.1. 微信小程序组件的曝光：

//component wxml
<view class="sensors-exposure-track1" data-sensors-exposure-event-name="trackView"></view>

// JS
Component({
	pageLifetimes:{
	  show(){
	    getApp().sensors.modules["Exposure"].addObserverByClassName("sensors-exposure-track1", {
        area_rate: 0.5,
        stay_duration: 0,
        repeated: false,
        component: this,
       });
	  },
      hide(){
      	getApp().sensors.modules["Exposure"].removeObserverByClassName("sensors-exposure-track1");
      }
	}
})
JS

4.2. 其他框架的曝光支持

对于 uni-app 、taro 等框架，目前不支持自动采集曝光。