1. Integration

Currently, the Web/Mini Program is gradually evolving into a plug-in architecture. The concept of "everything is a plug-in" will become more and more obvious.

Before using the plug-in, please refer to the plug-in usage for detailed operations.

1.1. ES Module Integration Method

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

JS

Version requirement

Requires WeChat Mini Program SDK v1.18.6 or above

2. Usage

Before using the Sensible Exposure feature, it is recommended to first understand the related introduction of Sensible Exposure: Exposure Collection.

2.1. Initialize the exposure plug-in and configure it

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

JS

2.1.1. Configuration Parameters

Parameter	Type	Default	Description
class_tags	Array<String>	['sensors-exposure-track']	The exposure tags set in the class attribute of the elements
area_rate	Number	0	Visible ratio of exposure, valid value range 0~1, The default value is 0, which means the element is considered visible as long as it is partially displayed The maximum value is 1, which means the element needs to be fully displayed to be considered visible
stay_duration	Number	0	Effective dwell time, in seconds The default value is 0, which means the element is considered visible as long as it meets the visibility ratio regardless of the dwell time
repeated	Boolean	true	Whether to allow collecting repeated exposure The default value is true, which means repeated exposure is allowed to be collected
framework	Object	None	In taro, this property needs to be set to define element exposure. The fixed value is `{ taro:Taro }` XML WeChat Mini Program SDK version 1.19.5 and above is supported

Attention:

The configuration set during initialization is to modify the global default configuration.
When marking view elements, if no configuration is passed, the global exposure configuration will be used.
When marking view elements, if a configuration is passed, the custom configuration will be used.
Different view elements can use different exposure configurations, and the exposure configurations correspond to the configurations passed when marking the view.
When using the API to add/refresh the original view mark, if a configuration is passed, the custom configuration passed when marking the view will be used after calling the API to detect the view elements.
When using the API to add/refresh the original view mark, if no configuration is passed, the configuration passed when marking the view last time will still be used after calling the API to detect the view elements.
Framework configuration. WeChat Mini Program SDK version 1.19.5 and above is supported.

2.2. Configure exposure elements.

2.2.1. Add exposure configuration to element attributes.

To configure exposure event collection, add the `class` attribute to the element and set the `data-sensors-exposure-option` attribute to unify the exposure configuration.

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

2.2.1.1. Configuration parameters.

Parameters.	Required.	Description.
class="sensors-exposure-track"	Yes.	The exposure mark set in the element's class attribute (must be added).
data-sensors-exposure-option	Yes.	Set the exposure configuration config and custom attributes properties for the current element.

2.2.1.2. option configuration parameters:

Parameter

Required

Description

event_name

Yes

Set the exposure event name (must be set)

config

No

Exposure element configuration. Same as initializing exposure configuration.

area_rate: Exposure ratio. Default: 0, value range: 0~1. Type: Number
stay_duration: Effective exposure duration. Default: 0. Type: Number
repeated: Repeated exposure. Default: true. Type: Boolean

properties

No

Custom attributes. Type: Object. Set custom attributes for the exposure event of this element. Support differentiation between upper and lower case and other types of attribute values.

2.2.2. Add exposure parameters separately through element configuration

Add the `class` tag to the element for exposure, and individually set the exposure event collection configuration for the corresponding element.

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

2.2.2.1. Configuration Parameters

Parameters	Required	Description
class="sensors-exposure-track"	Yes	Exposure tag set in the class attribute of the element (must add the tag)
data-sensors-exposure-event-name	Yes	Set the name of the exposure event (must be set)
data-sensors-exposure-config-area_rate	No	Set the exposure ratio
data-sensors-exposure-config-stay_duration	No	Set the duration of valid exposure stay
data-sensors-exposure-config-repeated	No	Set repeated exposure
data-sensors-exposure-property-*	No	Set custom attribute for this element's exposure event. The attribute value is a string and cannot be of other types.

2.2.3. Configure exposure parameters through 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 为曝光元素的元素信息及该元素的曝光自定义属性 	} })

JS

2.2.3.1. Configure parameters

Parameters

Required

Description

class_tag

Yes

Exposure tag set in the element's class attribute. Type: String

config

Yes

Exposure element configuration. It is the same as initializing exposure configuration.

area_rate: Exposure ratio. Default: 0, value range: 0~1. Type: Number
stay_duration: Effective exposure duration. Default: 0. Type: Number
repeated: Repeated exposure. Default: true. Type: Boolean
component: Component's this pointer. Default: None. Type: Object.

listener

No

The callback function when the current exposed element triggers an exposure event.

Supported in WeChat mini program SDK v1.19.5 and above.

shouldExpose: Whether to trigger the exposure event callback. Type: function
didExpose: The callback function when the exposure event is triggered. Type: function

3. Delete exposure tag listener via API

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

JS

Configuration parameters:

class_tag: Detection tag for the exposed element. Type: String. (Tag must be added)

Note

Registered exposure element tag class_tag, registering again only updates previously unregistered elements, registered elements will not be registered again, registered elements will not send exposure events due to calling the registration API.
If the element ID is not set, it is distinguished from the exposure element through the exposure element event-name (event name) and property (event attribute).
Each exposure element event-name (event name) or property (event attribute) or id (element ID) must be different, otherwise only the first element queried by exposure will be exposed.
WeChat mini program SDK version must be greater than or equal to 1.18.6.
The plugin and SDK must be in the same version. Do not mix SDK and plugin of different versions.

4. Adding exposure elements in different scenarios

4.1. Adding exposure to dynamically rendered elements

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

4.2. Registering exposure in a component

Add exposure tags and configurations in components/my-component/my-component.wxml. Supported in WeChat mini program SDK v1.19.5 and above.

<!--components/my-component/my-component.wxml--> <view class="sensors-exposure-track" data-sensors-exposure-event-name="component" > 	<text>曝光元素</text> </view>

XML

components/my-component/my-component.js pageLifetimes.onshow notify the SDK to update the exposure element

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

XML

4.3. Taro User Registration Exposure

app.js initializes WeChat mini-program SDK and exposure plugin. WeChat mini-program SDK version 1.19.5 and above are supported.

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

XML

pages/index/index.vue needs to add exposure configuration and notify SDK to update exposure elements.

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

XML

4.4. uni-app User Registration Exposure

main.js initializes WeChat mini-program SDK and exposure plugin.WeChat mini-program SDK version 1.19.5 and above are supported.

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

XML

pages/index/index.vue needs to add exposure configuration and notify SDK to update exposure elements.

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

XML