1. User Association

1.1. User Login

When the user successfully registers or logs in, you need to call the SDK's - login interface

sensorsdata::SensorsAnalytics::login("<#登录 id#>")

To accurately record the behavior information of logged-in users, it is recommended to call the - login: interface at the following timing

• When the user is successfully registered
• When the user logs in successfully
• Every time a logged-in user starts the app

2. User Attributes

• For the difference between event properties and user attributes, please refer to the data model
• Naming conventions for user attributes, please refer to the data format

2.1. Setting User Attributes

The -profileSet: method is used to set user attributes. When the same key is set multiple times, the value will be overwritten:

// 设定用户年龄属性 "Age" 为 18 sensorsdata::ObjectNode usersProperties; usersProperties.setNumber("Age", 18); sensorsdata::SensorsAnalytics::profileSet(usersProperties);

2.2. Record the initially set user attributes

For attributes that are only valid when set for the first time, we can use profileSetOnce to record these attributes. Unlike the profileSet method, if the attribute to be set already exists, this record will be ignored and existing data will not be overwritten. If the attribute does not exist, it will be automatically created. Therefore, profileSetOnce is suitable for setting attributes such as first activation time and first registration time. For example:

// 设定用户渠道为 "developer@sensorsdata.cn" 的 "AdSource" 属性值为 "XXX Store" sensorsdata::ObjectNode usersProperties; usersProperties.setString("AdSource", "XXX Store"); sensorsdata::SensorsAnalytics::profileSetOnce(usersProperties); // 再次设定用户渠道，设定无效， "AdSource" 属性值仍然是 "XXX Store" sensorsdata::ObjectNode usersProperties; sensorsdata::ObjectNode usersProperties; usersProperties.setString("AdSource", "Email"); sensorsdata::SensorsAnalytics::profileSetOnce(usersProperties);

3. Event Tracking Collection

After the SDK initialization is completed, you can perform data tracking through the following interfaces.

3.1. Code Tracking Event

After the SDK is initialized, you can track user behavior events and add custom properties to events using the - track: method.

The corresponding event name is: BuyProduct; the corresponding custom properties for the event are ProductID and UserLevel;

sensorsdata::ObjectNode eventProperties; // 设置商品类别 eventProperties.setString("ProductCatalog", "Laptop Computer"); // 设置商品 ID eventProperties.setNumber("ProductID", 3); sensorsdata::SensorsAnalytics::track("BuyProduct", eventProperties);

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 event -trackTimerStart: .This method does not actually send the event; At the end of the event, call-trackTimerEnd: ，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:

sensorsdata::SensorsAnalytics::trackTimerStart("ViewProduct"); sensorsdata::ObjectNode eventProperties; // 设置商品类别 eventProperties.setString("ProductCatalog", "Laptop Computer"); // 设置商品 ID eventProperties.setNumber("product_id", 3); sensorsdata::SensorsAnalytics::trackTimerEnd("ViewProduct", eventProperties);

When multiple call -trackTimerStart: , The start time of the event 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: and -trackTimerResume: to pause and resume, respectively. Called if the recorded duration event needs to be cleared -clearTrackTimer: interface.

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.

sensorsdata::ObjectNode itemProperties; // 设置商品类别 eventProperties.setString("ProductCatalog", "Laptop Computer"); // 设置商品 ID eventProperties.setNumber("product_id", 3); sensorsdata::SensorsAnalytics::itemSet("itemType", "itemId", itemProperties);

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.

sensorsdata::SensorsAnalytics::itemDelete("itemType", "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. Static public properties

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

// 将应用名称作为事件公共属性，后续所有追踪的事件都会自动带上 "AppName" 属性 sensorsdata::ObjectNode superProperties; // 设置商品类别 eventProperties.setString("AppName", "AppName"); sensorsdata::SensorsAnalytics::registerSuperProperties(superProperties);

Public properties will be stored in the local cache, App can pass - unregisterSuperProperties: delete one or more public properties; Or use -clearSuperProperties: to remove all the event public properties that have been set.

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

Every call -track: 、-login:、-profileSet:  method. 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. Is the interval between now and the last time data was sent greater than flushInterval?
   2. Is the number of local cached logs greater than flushBulkSize?
   3. Is the event type login() triggered $SignUp event?

The default flushBulkSize is 100, and the default flushInterval is 15 seconds. When the conditions are met, the Sensing Analytics SDK will compress the data with gzip and send it to Sensing Analytics in bulk.

To achieve timely data collection, you can call the -flush: method to force the data to be sent to Sensing Analytics. For example:

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

When the App enters the background state, the SDK will call the -flush: method to send the cached data to Sensing Analytics.

5.2. Set the network policy for sending data.

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

//指定只在 3G/4G/WIFI 条件下发送数据。 sensorsdata::SensorsAnalytics::setFlushNetworkPolicy(kFlush3G|kFlush4G|kFlushWiFi);

5.3. Clear local cached events.

You can use the deleteAll() method to delete all events stored locally in the app.

Do not call this method unless it is necessary.

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

6. Full Tracking

cocox2d-x supports two types of full tracking events: $AppStart (App start) and $AppEnd (App exit). To handle multiple processes, forced termination, and other scenarios, the Android SDK has a 30-second session mechanism. When a user exits the App to the background for 30 seconds, the exit event will be triggered, and when the App is restarted, the start event will be triggered. If the user reopens the App within 30 seconds, there will be no corresponding exit or start event. Additionally, if the process is not killed within 30 seconds after exiting the App to the background, the exit event will be triggered and attempted to be reported. If the process is killed, the exit event will be backfilled on the next startup. Therefore, when viewing the data, there are generally fewer exit events compared to start events.

6.1. Enable Full Tracking

The SDK can automatically collect some user behaviors, such as app startup and exit. When initializing the SDK, you can configure the types of full track you want to enable:

String SA_SERVER_URL = "数据接收地址";   // 初始化配置 SAConfigOptions saConfigOptions = new SAConfigOptions(SA_SERVER_URL); // 开启全埋点「启动、退出」 saConfigOptions.setAutoTrackEventType(SensorsAnalyticsAutoTrackEventType.APP_START |                 SensorsAnalyticsAutoTrackEventType.APP_END);   // 需要在主线程初始化神策 SDK SensorsDataAPI.startWithConfigOptions(this, saConfigOptions);

// 引入神策分析 SDK #import <SensorsAnalyticsSDK/SensorsAnalyticsSDK.h>   - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {       // 初始化配置     SAConfigOptions *options = [[SAConfigOptions alloc] initWithServerURL:<#数据接收地址#> launchOptions:launchOptions];     // 开启全埋点「启动、退出」     options.autoTrackEventType = SensorsAnalyticsEventTypeAppStart |                                  SensorsAnalyticsEventTypeAppEnd;       // 初始化 SDK     [SensorsAnalyticsSDK startWithConfigOptions:options];     ...     return YES; }