Please read the Data Model before use.
SDK update log, refer to Release Notes.

The sa-sdk-bytedancemini repository has been upgraded to the sa-sdk-mini repository for unified code management and iteration.

The sa-sdk-mini repository has added full-link tracking - page leave, and deprecated the sa.getPresetProperties and sa.getAnonymousID API.
The sa-sdk-bytedancemini repository is no longer maintained. If you need to use the old version SDK, please go to the old version SDK.

1. Integrate Sensors Analytics SDK

1.1. Import SDK

Obtain the Mini Program SDK source code from the GitHub mp-bytedance directory;
Put the index.esm.js file into the Mini Program project;
In the app.js file, import the SDK using import

import sensors from '/dist/mp-bytedance/index.esm';

JS

1.2. Initialize the SDK

Call the init() method to initialize the SDK.

sensors.init({ 	name: 'sensors', 	server_url: '您的数据接收地址', 	// 全埋点控制开关 	autoTrack: {}, 	// 自定义渠道追踪参数，如source_channel: ["custom_param"] 	source_channel: [], 	// 是否允许控制台打印查看埋点数据(建议开启查看) 	show_log: true });

JS

2. SDK Basic Configuration

2.1. Configure the project data receiving URL

Obtain the data receiving URL as shown below:

After obtaining the Data Receiving URL, set the server_url in the setPara interface. The domain name of server_url should be configured according to the requirements of Byte Mini Program https://microapp.bytedance.com/docs/zh-CN/mini-app/develop/guide/basic-ability/network） to configure the Mini Program server domain name.

2.2. Enable full point burial

autoTrack method, configure the types of full point burial to be enabled:

sensors.init({ 	autoTrack:{ 		appLaunch: true, // 默认为 true，false 则关闭 $MPLaunch 事件采集 		appShow: true, // 默认为 true，false 则关闭 $MPShow 事件采集 		appHide: true, // 默认为 true，false 则关闭 $MPHide 事件采集 		pageShow: true, // 默认为 true，false 则关闭 $MPViewScreen 事件采集 		mpClick: true // 默认为 true，false 则关闭 $MPClick 事件采集 	} 	/** 	 * 其他配置 	 */ });

JS

2.3. Set Event Common Properties

To add properties that are required for all events, register the properties as common properties before initializing the SDK:

sensors.registerApp({ 	userLever: 'VIP3', 	userSex: '男' });

JS

2.4. User Log In

When a user successfully registers or logs in, call the login() method and pass the login ID:

sensors.login("登录 ID");

JS

For users with automatic login, get the login ID and call the login() method before initializing the SDK.

2.5. Tracking Events with Code Instrumentation

After initializing the SDK, track user behavior events using the track() method and add custom properties to the events:

sensors.track(event_name [,properties]);

JS

Configuration parameters:

Parameter	Required	Description
event_name	True	Event name
properties	False	Add custom properties to user behavior events, type: Object.

Example:

// 为 click 事件添加自定义属性 name 值为点击。 sensors.track('click',{ 	name: '点击' });

JS

To learn about the format specifications for event names and event properties, refer to Data Format.

3. Debugging and viewing event information.

3.1. Event Trigger Logs

setPara() When configuring the initial parameters, use the "Configure" function.show_log: true Function (enabled by default) and SDK initialization completed (i.e. After the API call, the Byte Developer Tool.console Prints the collected data information:

3.2. Event sending status

When event data is successfully sent, you can see the sa request in the module of the Byte developer tool.

4. SDK optional configuration

4.1. User attributes can be set.

setProfile( properties ): When the same key is set multiple times, the value will be overwritten and replaced.

sensors.setProfile({ 	email:'xxx@xx', 	favoriteFruits: ['苹果', '油桃'], 	subscribers: 7277 });

JS

Regarding the difference between event properties and user properties, please refer todata model
User attribute naming constraints, please refer todata import
User Attribute Other Setting Methods, please refer toUser Attribute Set

4.2. Channel Track

When users access the mini-program through a path containing utm parameters, pre-set events are triggered. $MPLaunch、$MPShow can parse the launch path inutm relevant parameters are set as their own attributes and attribute values.$latest_utm related attributes are valid for all events throughout the lifecycle of the program.
Support custom channel tracking.