1. User association

The purpose of user association is to uniquely identify users and improve the accuracy of user behavior analysis. At present, we provide simple user association and global user association to support different business scenarios.

• Easy User Association (IDM 2.0)
• Global User Association (IDM 3.0)

2. User attribute

• For the difference between event properties and user properties, seedata model
• For naming restrictions on user attributes, seedata format

2.1. Records the user properties that were set for the first time

We can use properties that are only valid when first setprofileSetOnce()to record these attributes. Different fromprofileSet(), If the set user property already exists, the record is ignored without overwriting existing data, and is automatically created if the property does not exist. Therefore,profileSetOnce() This parameter is applicable to setting the first activation time and first registration time. For example:

// 设定用户渠道为 "developer@sensorsdata.cn" 的 "AdSource" 属性值为 "XXX Store" sensorsApiCloudSdk.profileSetOnce({ 	properties:{	 		AdSource: "XXX Store"	 	} }) // 再次设定用户渠道，设定无效， "AdSource" 属性值仍然是 "XXX Store" sensorsApiCloudSdk.profileSetOnce({ 	properties:{	 		AdSource: "Email"	 	} })

2.2. Attributes of a numeric type

For numeric user properties, you can use profileIncrement() Adds the property values. It is often used to record attributes such as the number of user payments, payment amount, and points. For example:

// 将用户游戏次数属性增加一次 sensorsApiCloudSdk.profileIncrement({ 	properties:{chinese:60, math:70} });

2.3. Properties of a list type

For the user's favorite movies, restaurants reviewed by the user and other attributes, you can record the column phenotype attributes, such as:

// 设定用户观影列表属性，设定后属性 "Movies" 为: ["Sicario", "Love Letter"] sensorsApiCloudSdk.profileAppend({ 	property:'Movies',value: ["Sicario", "Love Letter"] });

Note that the element in the column phenotype attribute must be String type. See column phenotypic restrictionsdata format.

2.4. Attribute cancellation

If you want to cancel a user property that has been set, you can call profileUnset() to cancel:

sensorsApiCloudSdk.profileUnset({ 	property:'Movies' });

3. Buried point event acquisition

After SDK initialization is complete, you can bury data through the following interface.

3.1. Code bury trace event

After SDK initialization, you can usetrack() method tracks user behavior events and adds custom properties to events.

//触发一条 BuyProduct 事件，同时设置商品 ID、商品类别属性 sensorsApiCloudSdk.track({ event:'BuyProduct', properties:{ ProductID:'PRODUCT_ID', ProductCatalog:'Laptop Computer', 		ProductPrice: 100 } });

For the format specifications of event names and event attributes, seedata format.

3.2. Buried event collection duration attribute

You can count the duration of an event with a timer. First, it is called at the beginning of the eventtrackTimerStart("Event") ，This method does not actually send the event; At the end of the event, calltrackTimerEnd("Event", properties)，SDK will trigger"Event" event, And automatically records the event duration in the event properties "$event_duration" . For example, record the time users spend browsing product pages:

sensorsApiCloudSdk.trackTimerStart({event:'ViewProduct'});   // 调用 track，记录 ViewProduct 事件，并在属性 event_duration 中记录用户浏览商品的时间 sensorsApiCloudSdk.trackTimerEnd({ event:'ViewProduct' properties:{        product_id:'PRODUCT_ID' } });

When multiple calling trackTimerStart , event "Event" the start time is based on the last call.Note It is important to ensure that the trackTimerStart and trackTimerEnd interfaces are used together. Calling trackTimerEnd multiple times will trigger an eternally-buried event.

Statistical event duration supports pause and recovery by callingtrackTimerPause and trackTimerResume to pause and resume, respectively. Called if the recorded duration event needs to be clearedclearTrackTimer api.

3.3. Item metadata report

3.3.1. Set item properties

Set an item directly and overwrite it if it already exists. In addition to the item ID and the type the item belongs to, other item properties need to be defined in Properties. In item attributes, the constraints on the attribute name and attribute value are the same as those on event attributes. For details, please refer todata format.

// 为物品类型为 itemType 且物品 ID 为 itemId 的物品，设置物品属性   sensorsApiCloudSdk.itemSet({ 	itemType: 'itemType', 	itemId: 'itemId', 	properties: { 		itemProperty: 'itemPropertyValue' 	} });

3.3.2. Delete item attributes

If the item cannot be recommended and needs to go offline, just delete it, or ignore it if it does not exist. Other than the item ID and type of the item, no other item attributes are parsed.

// 删除物品，类型为 itemType，ID 为 itemId   sensorsApiCloudSdk.itemDelete({itemType: 'itemType', itemId: 'itemId'});

4. Event attribute

When tracking buried events, you can define buried event attributes as required. At present, the SDK provides public attributes for adding attributes to each buried point event, and public attributes are divided into static public attributes and dynamic public attributes. Static public properties are used to set the properties with low update frequency, and dynamic public properties are used to set the properties with high update frequency. When a property of the same Key appears in the same event, the SDK overrides the priority: preset property < Static public attribute < Dynamic public attribute < Custom properties.

4.1. Get preset properties

Can call getPresetProperties() method Obtain preset properties. If the embedded point on the server requires some preset properties on the App, you can obtain the preset properties on the App in this method and send them to the server.

//获取预置属性   var result = sensorsApiCloudSdk.getPresetProperties();

4.2. Static public attribute

Static public properties are properties that need to be added for all events, and can be passed after initializing the SDKregisterSuperProperties() Register the property as a public property. The setting method is as follows:

// 将应用名称作为事件公共属性，后续所有 track 类型的事件都会自动带上 "PlatformType" 属性 sensorsApiCloudSdk.registerSuperProperties({properties:{ PlatformType:"Android"}});

Registered static public attributes can use unregisterSuperProperty method to delete the static public attribute of the specified key.

sensorsApiCloudSdk.unregisterSuperProperty({property:'PlatformType'});

5. Data storage and sending

You need more fine-grained control over your analytics and can set up the data acquisition function with the following options.

5.1. Data acquisition

On every call track()、login()、profileSet() The SDK will save the buried event in the database and check the following conditions to determine whether to upload data to the server:

1. Whether WIFI/2G/3G/4G/5G network conditions
2. Whether one of the sending conditions is met:
   1. Whether the time interval between the last sending is greater thanflushInterval
   2. Whether the number of local cache logs is greater than flushBulkSize
   3. The type of event is login() method triggers $SignUp event

Default flushBulkSize is 100, default flushInterval is 15 seconds. After the conditions are met, the SDK will gzip the data and send it to the SDK in batches.

If the pursuit of timeliness of data collection, you can call flush() method, Force data to be sent to divine analytics, for example:

	// 记录用户登录事件 	sensorsApiCloudSdk.track({ event:'userLogin', 	 properties:{ 	name:'userName', 	age:28 	} 	}); 	// 强制发送数据 	sensorsApiCloudSdk.flush();	

The SDK is called when the App enters the background stateflush() method, send cached data to Sensors Analysis.

5.2. Set the network policy for sending data

By default, the SDK will attempt to synchronize data on WIFI/3G/4G/5G networks.sensors.setFlushNetworkPolicy()method to specify a network policy for sending data. For example:

/** * 设置 flush 时网络发送策略，默认 3G、4G、WI-FI 环境下都会尝试 flush * TYPE_NONE = 0;//NULL * TYPE_2G = 1;//2G * TYPE_3G = 1 << 1;//3G 2 * TYPE_4G = 1 << 2;//4G 4 * TYPE_WIFI = 1 << 3;//WIFI 8 * TYPE_5G = 1 << 4;//5G 16 * TYPE_ALL = 0xFF;//ALL 255 * 例：若需要开启 4G 5G 发送数据，则需要设置 4 + 16 = 20 */ //指定只在 3G/4G/WIFI 条件下发送数据。 sensorsApiCloudSdk.setFlushNetworkPolicy({networkPolicy:14});

5.3. SDK Network request switch

The SDK provides the enableNetworkRequest(boolean isRequest) interface to control network requests of the SDK. If true, the SDK is allowed to initiate network requests; if false, the SDK is forbidden to initiate network requests. When using the SDK, you must pay attention to the call time to prevent the SDK from being in the disabled network state, resulting in the failure to report events in time.

// 开启网络请求 sensorsApiCloudSdk.enableNetWorkRequest({isRequest: true }); // 禁用网络请求 sensorsApiCloudSdk.enableNetWorkRequest({isRequest: false }); 

5.4. Clear local cache events

Can usedeleteAll() method to delete all events stored locally in the App.

Do not call this method unless specifically requested.

//删除 App 本地存储的所有事件 sensorsApiCloudSdk.deleteAll();

6. Full buried point

The full buried point refers to $AppStart (App startup) and $AppEnd (App exit).
For App startup and exit, the Android SDK adds a 30-second session mechanism in order to cope with scenarios such as multi-process and forced killing. The exit event will be triggered only when the user exits the App to the background for 30 seconds, and the startup event will be triggered only when the App is started again. If the user opens the App within 30 seconds, there is no corresponding exit event and startup event. In addition, if the process is not killed within 30 seconds of exiting the App to the background, then the exit event will be triggered and attempt to report, if the process is killed, then the exit event will be reissued at the next startup. Therefore, when viewing the data, there are generally fewer exit events than startup events.

6.1. Open the full burial point

SDK can automatically collect some user behaviors, such as App start and exit. You need to enable it in module configuration (config.xml):

<feature name="sensorsAnalyticsAPICloudSDK"> 	... <param name="enableAutoTrack" value="true"/> 	... </feature>

6.2. Manually trigger full-sampling events

Manually triggering full-sampling events means that developers actively call the interfaces provided by the SDK to trigger App page browsing events.

6.2.1. Manually trigger page browsing events

The trackViewScreen() method can be used to manually trigger App page browsing events.

var argument={url:"https://www.sensorsdata.cn/manual/apicloud_sdk.html",properties:{"$title":"主页","$screen_name":"cn.sensorsdata.demo.HomePage"}}; sensorsApiCloudSdk.trackViewScreen(argument);