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 set profileSetOnce()to record these properties. Different from profileSet(), 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:

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

2.2. Attributes of a numeric type

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

// 将用户游戏次数属性增加一次 SensorsAnalyticsFlutterPlugin.profileIncrement("GamePlayed", 1);

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:

SensorsAnalyticsFlutterPlugin.profileAppend('address',['Beijing','Shanghai']);

Note that the element in the column phenotype attribute must beString 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：

SensorsAnalyticsFlutterPlugin.profileUnset("age");

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.

SensorsAnalyticsFlutterPlugin.track('eventname',{'ProductID':'123456','ProductCatalog':'Laptop Computer'});

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:

// 进入商品页面 // 调用 trackTimerStart("ViewProduct") 标记事件启动时间 SensorsAnalyticsFlutterPlugin.trackTimerStart("ViewProduct"); // ... 用户浏览商品 // 离开商品页 SensorsAnalyticsFlutterPlugin.trackTimerEnd('ViewProduct',{"product_id":PRODUCT_ID});

Multiple call trackTimerStart("Event") , 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 calling trackTimerPause(String eventName) and trackTimerResume(String eventName) Pause and resume respectively. Called if the recorded duration event needs to be cleared clearTrackTimer() 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 的物品，设置物品属性 properties SensorsAnalyticsFlutterPlugin.itemSet(String itemType, String itemId, [Map<String, dynamic>? properties]);

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 SensorsAnalyticsFlutterPlugin.itemDelete(String itemType, String itemId);

4. Event attribute

When tracking buried events, you can define buried event attributes as required. Currently, the SDK provides public attributes for adding attributes to each buried event. 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.

//获取预置属性 SensorsAnalyticsFlutterPlugin.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 类型的事件都会自动带上 "AppName" 属性 SensorsAnalyticsFlutterPlugin.registerSuperProperties({"AppName":"FlutterDemo"});

Registered static public attributes can use unregisterSuperProperty(String key) method to delete static public properties of the specified key, also available useclearSuperProperties() delete all registered public properties

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 than flushInterval
   2. Whether the number of local cache logs is greater thanflushBulkSize
   3. Event type islogin() 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 callflush() method, force data to be sent to divine analysis, for example：

// 记录用户登录事件 SensorsAnalyticsFlutterPlugin.track("UserLogin"); // 强制发送数据 SensorsAnalyticsFlutterPlugin.flush();

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

5.2. Set the network policy for sending data

By default, the SDK will attempt to synchronize data on WIFI/3G/4G/5G networks.v1.7.2 and later versions support network policies that can be customized to synchronize data. UseSAConfigOptions.setNetworkTypePolicy() At initialization orSensorsDataAPI.setFlushNetworkPolicy() method to specify a network policy for sending data. For example:

//SANetworkType 为支持的网络类型枚举 SensorsAnalyticsFlutterPlugin.setFlushNetworkPolicy(Set<SANetworkType> networkType)

5.3. Example Set the upper limit of local cache

The upper limit of the default cached data in the SDK local database varies according to different platforms SensorsAnalyticsFlutterPlugin.init() method configuration, As follows：