Advanced guide
1. Set user IDs
By default, the SDK instance uses a random number as each user's default distinct ID, which serves as the user's identifier while the user is not logged in. Note that the distinct ID changes when the user reinstalls the app or switches devices.
1.1 Set the distinct ID
In general, you don't need to customize the distinct ID. Make sure you understand the user identification rules before you set a distinct ID.
If you need to replace the distinct ID, call the method immediately after the SDK is initialized. Do not call it multiple times, to avoid creating useless accounts.
If your app has its own distinct ID management system for each user, you can call Identify to set the distinct ID:
// Set the distinct ID to Thinker
ThinkingAnalyticsAPI::Identify("Thinker");
To get the current distinct ID, call DistinctID():
//Return the distinct ID
ThinkingAnalyticsAPI::DistinctID().c_str()
1.2 Set the account ID
When a user logs in, you can call Login to set the user's account ID. The AE platform uses the account ID as the identifier, and the account ID you set is kept until LogOut is called. Calling Login multiple times overwrites the previous account ID
// The unique login identifier of the user, which corresponds to #account_id in the reported data. In this case, the value of #account_id is TA
ThinkingAnalyticsAPI::Login("TA");
This method does not upload a login event
1.3 Clear the account ID
After a user logs out, you can call LogOut to clear the account ID. Until Login is called again, the distinct ID is used as the identifier.
ThinkingAnalyticsAPI::LogOut();
We recommend calling LogOut only on explicit logout events, for example when the user deletes their account, rather than when the app is closed.
This method does not upload a logout event
2. Send events
After the SDK is initialized, you can start tracking data to collect user behavior. In most cases, regular events meet business needs. You can also use first events, updatable events, and other event types based on your actual business scenarios.
2.1 Regular events
You can call Track to upload events. We recommend setting event properties and the conditions for sending events according to the document you prepared earlier. The following example tracks a user purchasing a product:
//Store purchase event
TDJSONObject event_properties;
event_properties.SetString("product_name", "Product Name");
ThinkingAnalyticsAPI::Track("product_buy", event_properties);
2.2 First events
A first event is an event that is recorded only once for a given device or an ID of another dimension. For example, in some scenarios you may want to record the activation event on a device; you can report this data as a first event.
TDJSONObject jsonObject1;
jsonObject1.SetString("test","test");
TDFirstEvent *firstEvent = new TDFirstEvent("device_activation",jsonObject1);
ThinkingAnalyticsAPI::Track(firstEvent);
delete firstEvent;
If you want to determine whether an event is the first one based on a dimension other than the device, you can customize first_check_id for the first event:
//Set the user ID as the first_check_id of the first event to track first-time user activation
TDJSONObject jsonObject1;
jsonObject1.SetString("test","test");
TDFirstEvent *firstEvent = new TDFirstEvent("account_activation",jsonObject1);
firstEvent->setFirstCheckId("TA");
ThinkingAnalyticsAPI::Track(firstEvent);
delete firstEvent;
Note: Because the first-event check is performed on the server, first events are stored with a 1-hour delay by default.
2.3 Updatable events
You can use updatable events to modify event data in specific scenarios. An updatable event requires an ID that identifies the event, which you pass in when you create the updatable event object. The AE backend determines which data to update based on the event name and event ID.
// Example: report an updatable event, assuming the event name is UPDATABLE_EVENT
// After reporting, the event property status is 3 and price is 100
TDJSONObject jsonObject;
jsonObject.SetNumber("status", 3);
jsonObject.SetNumber("price", 100);
TDUpdatableEvent *updatableEvent = new TDUpdatableEvent("UPDATABLE_EVENT",jsonObject,"test_event_id");
ThinkingAnalyticsAPI::Track(updatableEvent);
delete updatableEvent;
// After reporting, the event property status is updated to 5 and price is unchanged
TDJSONObject jsonObject1;
jsonObject1.SetNumber("status", 5);
TDUpdatableEvent *updatableEvent1 = new TDUpdatableEvent("UPDATABLE_EVENT",jsonObject1,"test_event_id");
ThinkingAnalyticsAPI::Track(updatableEvent1);
delete updatableEvent1;
2.4 Overwritable events
Overwritable events are similar to updatable events, except that an overwritable event completely overwrites historical data with the latest data. In effect, the previous record is deleted and the latest data is ingested. The AE backend determines which data to update based on the event name and event ID.
// Example: report an overwritable event, assuming the event name is OVERWRITE_EVENT
// After reporting, the event property status is 3 and price is 100
TDJSONObject jsonObject;
jsonObject.SetNumber("status", 3);
jsonObject.SetNumber("price", 100);
TDOverWritableEvent *event = new TDOverWritableEvent("OVERWRITE_EVENT",jsonObject,"test_event_id");
ThinkingAnalyticsAPI::Track(event);
delete event;
// After reporting, the event property status is updated to 5 and the price property is deleted
TDJSONObject jsonObject1;
jsonObject1.SetNumber("status", 5);
TDOverWritableEvent *event1 = new TDOverWritableEvent("OVERWRITE_EVENT",jsonObject1,"test_event_id");
ThinkingAnalyticsAPI::Track(event1);
delete event1;
2.5 Super properties
Super properties are properties that are uploaded with every event.
2.5.1 Static super properties
Static super properties are properties that change infrequently and are carried by every event, such as a user's membership level. After you set static super properties through SetSuperProperty, the SDK adds them to each event as event properties when the event is collected.
TDJSONObject superProperties;
superProperties.SetNumber("vip_level",2);
ThinkingAnalyticsAPI::SetSuperProperty(superProperties);
Static super properties are saved in the cache, so you don't need to set them every time the app starts. If a property already exists, the newly set value overwrites the original value; if the property doesn't exist, a new property is created. In addition to setting properties, we also provide other APIs for managing static super properties to meet everyday business needs.
//Clear a super property
ThinkingAnalyticsAPI::UnsetSuperProperties("Channel");
//Clear all super properties
ThinkingAnalyticsAPI::ClearSuperProperty();
//Get all super properties
TDJSONObject superJson;
ThinkingAnalyticsAPI::GetSuperProperties(superJson);
2.5.2 Dynamic super properties
Dynamic super properties are properties that change frequently and are carried by every event, such as the number of coins a user has. After you set the dynamic super property class through SetDynamicSuperProperties, the SDK automatically gets the properties when an event is collected and adds them to the triggered event.
TDJSONObject GetDynamicSuperProperties(){
TDJSONObject json;
json.SetNumber("coin",10);
return json;
}
ThinkingAnalyticsAPI::Init(config);
ThinkingAnalyticsAPI::SetDynamicSuperProperties(GetDynamicSuperProperties);
2.6 Track event duration
To record how long an event lasts, call timeEvent to start timing. Specify the name of the event you want to time; when you upload that event, the #duration property is automatically added to its event properties to indicate the recorded duration in seconds. Note that only one timing task can run for the same event name at a time.
//The following example measures how long a user stays on a product page
//The user enters the product page and timing starts
ThinkingAnalyticsAPI::TimeEvent("stay_shop");
/**do something
.......
**/
//The user leaves the product page and timing ends. The "stay_shop" event will carry the #duration property that indicates the event duration
TDJSONObject event_properties;
ThinkingAnalyticsAPI::Track("stay_shop", event_properties);
3. User properties
The user property APIs currently supported by the AE platform are UserSet, UserSetOnce, UserAdd, UserUnset, UserDelete, UserAppend, and UserUniqAppend.
3.1 UserSet
For general user properties, you can call UserSet to set them. Properties uploaded through this API overwrite the original values. If the user property doesn't exist yet, it is created with the same type as the value passed in. The following example sets the username:
TDJSONObject userProperties;
userProperties.SetString("username", "TA");
ThinkingAnalyticsAPI::UserSet(userProperties);
//username is now AE
TDJSONObject userProperties1;
userProperties1.SetString("username", "AE");
ThinkingAnalyticsAPI::UserSet(userProperties1);
3.2 UserSetOnce
If a user property only needs to be set once, you can call UserSetOnce to set it. If the property already has a value, this call is ignored. The following example sets the first payment time:
//first_payment_time is 2018-01-01 01:23:45.678
TDJSONObject userProperties;
userProperties.SetString("first_payment_time","2018-01-01 01:23:45.678");
ThinkingAnalyticsAPI::UserSetOnce(userProperties);
//first_payment_time is still 2018-01-01 01:23:45.678
TDJSONObject userProperties1;
userProperties1.SetString("first_payment_time","2018-12-31 01:23:45.678");
ThinkingAnalyticsAPI::UserSetOnce(userProperties1);
3.3 UserAdd
When you upload a numeric property, you can call UserAdd to accumulate its value. If the property has not been set yet, it is assigned 0 before the calculation. You can pass a negative value, which is equivalent to subtraction. The following example accumulates the total payment amount:
//total_revenue is now 30
TDJSONObject userProperties;
userProperties.SetNumber("total_revenue",30);
ThinkingAnalyticsAPI::UserAdd(userProperties);
//total_revenue is now 678
TDJSONObject userProperties1;
userProperties1.SetNumber("total_revenue",648);
ThinkingAnalyticsAPI::UserAdd(userProperties1);
The property key is a string, and the Value can only be a number.
3.4 UserUnset
If you need to reset a property of a user, you can call UserUnset to clear the value of the specified user property. This API accepts a string or a list as the parameter:
ThinkingAnalyticsAPI::UserUnset("userUnset_key");
The value passed in is the Key of the property to clear.
3.5 UserDelete
To delete a user, you can call UserDelete. After that, you can no longer query this user's user properties, but the events generated by the user can still be queried.
ThinkingAnalyticsAPI::UserDelete();
3.6 UserAppend
You can call UserAppend to append elements to user properties of the List type:
TDJSONObject userProperties;
vector<string> listValue;
listValue.push_back("apple");
listValue.push_back("ball");
userProperties.SetList("user_list",listValue);
ThinkingAnalyticsAPI::UserAppend(userProperties);
3.7 UserUniqAppend
You can call UserUniqAppend to append elements to an array-type user property. Calling UserUniqAppend deduplicates the appended user property values, whereas the UserAppend API doesn't deduplicate, so the user property may contain duplicates.
//The value of user_list is now ["apple","ball"]
TDJSONObject userProperties1;
vector<string> listValue1;
listValue1.push_back("apple");
listValue1.push_back("ball");
userProperties1.SetList("user_list",listValue1);
ThinkingAnalyticsAPI::UserAppend(userProperties1);
//The value of user_list is now ["apple","apple","ball","cube"]
TDJSONObject userProperties2;
vector<string> listValue2;
listValue2.push_back("apple");
listValue2.push_back("cube");
userProperties2.SetList("user_list",listValue2);
ThinkingAnalyticsAPI::UserAppend(userProperties2);
//The value of user_list is now ["apple","ball","cube"]
ThinkingAnalyticsAPI::UserUniqAppend(userProperties2);
4. Encryption
Starting from v1.3.7, the SDK supports encrypting data with AES+RSA. Data encryption requires cooperation between the client and the server. For details, contact your customer success representative.
TDConfig config;
config.appid = appid;
config.server_url = server_url;
config.EnableEncrypt(1,"publickKey");
ThinkingAnalyticsAPI::Init(config);
5. Other features
5.1 Print SDK logs
You can call the EnableLog API to turn on the SDK log switch. Once it is on, the reported data is printed in the IDE console.
ThinkingAnalyticsAPI::EnableLog(true);
5.2 Preset properties
| Property name | Display name | Property type | Description |
|---|---|---|---|
| #ip | IP address | Text | The user's IP address, which AE uses to get the user's geographic location |
| #country | Country | Text | The user's country, generated from the IP address |
| #country_code | Country code | Text | The country code of the user's country (ISO 3166-1 alpha-2, that is, two uppercase letters), generated from the IP address |
| #province | Province | Text | The user's province, generated from the IP address |
| #city | City | Text | The user's city, generated from the IP address |
| #os | OS | Text | For example, macOS, Windows |
| #device_id | Device ID | Text | The user's device ID |
#lib | SDK type | Text | The type of SDK you integrated, such as Android and iOS |
| #lib_version | SDK version | Text | The version of the SDK you integrated |
5.3 Calibrate time
By default, the SDK uses the local device time as the event time. If users manually change the device time, your business analysis may be affected. In this case, you can calibrate the time to keep the event time accurate. We provide two time calibration methods: timestamp and automatic.
- You can calibrate the SDK time with the current timestamp obtained from the server. After that, all calls that don't specify a time, including event data and user property operations, use the calibrated time as the time of occurrence.
// 1585633785954 is the current Unix timestamp in milliseconds, corresponding to Beijing time 2020-03-31 13:49:45
ThinkingAnalyticsAPI::CalibrateTime(1585633785954);
- You can also enable automatic time calibration. The SDK then tries to get the current time from the config API and calibrates the SDK time. If no correct response is received, data is reported with the local time afterward.
TDConfig config;
config.appid = appid;
config.server_url = server_url;
config.enableAutoCalibrated = true;
ThinkingAnalyticsAPI::Init(config);
5.4 Flush data immediately
In some business scenarios, if you want data to be reported to the AE server immediately, you can call the flush API
ThinkingAnalyticsAPI::Flush();
5.5 Get the device ID
You can call getDeviceId to get the device ID:
ThinkingAnalyticsAPI::GetDeviceId();
5.6 Set the default time zone
By default, the SDK reports the local device time at the moment of the API call as the event time. You can also specify a default time zone through the API for setting the default time zone, so that the event time of all events is aligned to the time zone you set:
TDConfig config;
config.appid = appid;
config.server_url = server_url;
config.zoneOffset = 5;
ThinkingAnalyticsAPI::Init(config);
Note: Aligning the event time to a specified time zone discards the device's local time zone information. To keep the device's local time zone information, you currently need to add the relevant properties to events yourself.