1. Integration

Currently, Web/Mini Programs are gradually evolving into a plugin-based architecture. The concept of "everything is a plugin" will become more prominent.

Before using the plugin, please refer to the plugin usage guide

1.1. ES Module Integration Method

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

JS

Version Requirement

Web SDK v1.23.5 and above

2. Usage

Before using the Sensors Analytics exposure function, it is recommended to first understand the relevant introduction of Sensors Analytics exposure: Exposure Collection

2.1. Initialize the exposure plugin and configuration

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. Configuration Parameters

The SDK provides initialization to set exposure conditions. The specific parameter descriptions are as follows:

Parameter

Type

Default

Description

area_rate

Number

0

The visible percentage of exposure, valid value range is 0~1,

The default value is 0, which means that the element only needs to be partially visible to meet the visibility ratio condition.
The maximum value is 1, which means that the element needs to be fully visible to meet the visibility ratio condition.

stay_duration

Number

0

Effective stay duration, in seconds.

The default value is 0, which means that the element only needs to meet the visibility ratio for the effective stay duration to be satisfied.

repeated

Boolean

true

Whether to allow collection of repeated exposures.

The default value is true, which allows the collection of repeated exposures.

Note:

The initial configuration is to modify the global default settings.
If no configuration item is passed when marking the view element, the global exposure configuration will be used.
If a configuration item is passed when marking the view element, the custom configuration will be used.

2.2. Register the exposed element.

2.2.1. Configure exposure for element attributes separately.

<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. Configuration parameters

Metric parameter	Required	Description
data-sensors-exposure-event-name	Yes	Sets the exposure event name (required)
data-sensors-exposure-config-area_rate	No	Sets the exposure rate
data-sensors-exposure-config-stay_duration	No	Sets the duration of valid exposure stay
data-sensors-exposure-config-repeated	No	Sets repeated exposure
data-sensors-exposure-property-*	No	Sets custom properties for the exposure event. The property value should be a String and cannot be other types.

Note:

data-sensors-exposure-event-name must be set
Configuration Priority: Element-specific Settings > Element Universal Settings > addExposureView Settings > Plugin Initialization Settings
Custom attribute names are case-insensitive.
Custom attribute value type can only be String.

2.2.2. Unified configuration of element attributes for exposure settings.

// 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. Configuration parameters

Parameters	Required	Description
data-sensors-exposure-event-name	Yes	Set the exposure event name (must be set).
data-sensors-exposure-option	No	Set the exposure configuration config and custom attribute properties for the current element.

Note:

web SDK v1.25.6 and above support
Set the exposure event name (must be set) with data-sensors-exposure-name
Configuration Priority: Element-specific Settings > Element Universal Settings > addExposureView Settings > Plugin Initialization Settings

2.2.3. API registers exposed elements.

// 初始化曝光 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. Configuration parameters:

parameters	required	description
element	Yes	Element where exposure events need to be collected
option	Yes	Exposure element configuration.

2.2.3.2. option configuration parameters:

parameters	required	description
eventName	Yes	Set the exposure event name (must be set)
config	No	Exposure element configuration. Same as the initialization exposure configuration. area_rate: Exposure rate. Default: 0, value range: 0~1. Type: Number stay_duration: Valid exposure duration. Default: 0. Type: Number repeated: Repeated exposure. Default: true. Type: Boolean
properties	No	Custom attributes. Type: Object. Same as track custom attributes
listener	No	The listener callback when the current exposure element triggers the exposure event. Support in web SDK v1.25.6 and above versions. shouldExpose: Whether to trigger the exposure event callback. Type: function didExpose: The callback that has been triggered a few times. Type: function

Note:

The option.listener function is supported in web SDK v1.25.6 and above versions.
Configuration priority: Individual element settings > Uniform element settings > addExposureView settings > Initialization plugin settings

2.3. Unregister exposure element

// 初始化曝光 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

Configuration parameters:

Parameter	Required	Description
element	Yes	Element of exposure events that need to be collected. Type: HTMLElement

Note

Plugins and SDKs must be used in the same version. Do not mix different versions of SDKs and plugins.