1. 集成

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

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

1.1.  ES Module 集成方式

import Exposure from '/dist/web/plugin/exposure/index.es6';  
var exposure = sensors.use(Exposure, {
  area_rate: 0, 
  stay_duration: 2, 
  repeated: true 
});
JS

版本要求

Web SDK v1.23.5及以上版本

2. 使用

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

2.1. 初始化曝光插件及配置

import Exposure from '/dist/web/plugin/exposure/index.es6';
var exposure = sensors.use(Exposure, {
  area_rate: 0, 
  stay_duration: 2, 
  repeated: true 
});
JS

2.1.1. 配置参数

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

参数类型默认描述
area_rate

Number

0

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

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

stay_duration

Number

0

有效停留时长,单位为秒

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

repeated

Boolean

true

是否允许采集重复曝光

  • 默认值为 true,及允许采集重复曝光

注意:

  • 初始化设置的配置,是修改全局的默认配置。
  • 标记视图元素时,如果不传入配置项,则会使用全局曝光配置
  • 标记视图元素时,如果传入配置项,则会使用传入的自定义配置

2.2. 注册曝光元素

2.2.1. 元素属性单独配置曝光配置


<div 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"></div>
XML

2.2.1.1. 配置参数

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

注意:

  • data-sensors-exposure-event-name  必须设置
  • 配置优先级: 元素单独设置 > 元素统一设置 > addExposureView 设置 > 初始化插件设置
  • 自定义属性名称无法区分大小写
  • 自定义属性值类型仅为 String

2.2.2. 元素属性统一配置曝光配置

// index.html
<div id="exposure_div"></div>
// index.js
var exposureDiv = document.getElementById("exposure_div");
// 设置曝光元素事件名称
exposureDiv.setAttribute("data-sensors-exposure-event-name", "exposure_ele");

// 设置曝光元素配置及自定义属性
exposureDiv.setAttribute(
  "data-sensors-exposure-option",
  JSON.stringify({
    config: {
      area_rate: 0.5,
      stay_duration: 0,
      repeated: true
    },
    properties: {
      d: "abc",
      e: false
    }
  })
);
XML

2.2.2.1. 配置参数

参数必填描述
data-sensors-exposure-event-name 

设置曝光事件名称(必须设置)

data-sensors-exposure-option

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

注意: 

  •  web SDK  v1.25.6及以上版本支持
  • data-sensors-exposure-name 设置曝光事件名称 (必须设置)
  • 配置优先级: 元素单独设置 > 元素统一设置 > addExposureView 设置 > 初始化插件设置

2.2.3. API 注册曝光元素

// 初始化曝光
import Exposure from '/dist/web/plugin/exposure/index.es6';
var exposure = sensors.use(Exposure, {
  area_rate: 0, 
  stay_duration: 2, 
  repeated: true 
});

// 调用 API
exposure.addExposureView(document.getElementById("exposure_ele"), {
  eventName: "exposure_ele",
  config: {
    area_rate: 0.5,
    stay_duration: 0,
    repeated: true
  },
  properties: {
    d: "abc",
    e: false
  },
  listener: {
    // 是否触发曝光事件
    shouldExpose: function (ele, properties) {
      // ele 为当前曝光的元素
      // properties 为曝光元素的元素信息及该元素的曝光自定义属性
      // 触发曝光事件则返回 true
      // 不触发曝光事件则返回 false
      return true;
    },
    // 已触发曝光回调
    didExpose: function (ele, properties) {
      // ele 为当前曝光的元素
      // properties 为曝光元素的元素信息及该元素的曝光自定义属性
    }
  }
});
JS

2.2.3.1. 配置参数:

参数必填描述

element

需要采集曝光事件的元素

option

曝光元素配置。

2.2.3.2. option 配置参数:

参数必填描述

eventName

设置曝光事件名称(必须设置)

config

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

  • area_rate: 曝光比例。默认: 0,值域: 0~1。类型:Number
  • stay_duration: 有效曝光停留时长。 默认: 0。类型:Number
  • repeated: 重复曝光。 默认: true。类型: Boolean
properties自定义属性。类型: Object。同 track 自定义属性
listener

当前曝光元素触发曝光事件时的监听回调。 web SDK  v1.25.6及以上版本支持

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

注意:

  • option.listener 功能 web SDK  v1.25.6及以上版本支持
  • 配置优先级: 元素单独设置 > 元素统一设置 > addExposureView 设置 > 初始化插件设置

2.3. 注销曝光元素

// 初始化曝光
import Exposure from '/dist/web/plugin/exposure/index.es6';
var exposure = sensors.use(Exposure, {
  area_rate: 0, 
  stay_duration: 2, 
  repeated: true 
});


exposure.removeExposureView(document.getElementById('exposure_ele'))
JS

配置参数:

参数必填描述

element

需要采集曝光事件的元素。类型:HTMLElement


注意

  • 插件和 SDK 必须在同一个版本中,请勿混合不同版本的 SDK 和插件进行使用。