Advanced guide
1. 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.
1.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:
TDPropertiesNode event_properties;
event_properties.SetString("name1", "XZ_debug");
event_properties.SetString("name2", "logbugs");
event_properties.SetString("name3", "name3");
event_properties.SetString("#uuid", "1234567890");
event_properties.SetNumber("test_number_int", 3);
event_properties.SetNumber("test_number_double", 3.14);
event_properties.SetBool("test_bool", true);
std::string test_string = "test_string";
event_properties.SetString("test_stl_string1", test_string);
event_properties.SetDateTime("test_time1", time(nullptr), 0);
timeb t = {};
ftime(&t);
event_properties.SetDateTime("#time", t.time, t.millitm);
std::vector<std::string> test_list;
test_list.push_back("item11");
test_list.push_back("item21");
event_properties.SetList("test_list1", test_list);
// track event
te.track("accountId", "distinctId", "eventName", event_properties);
1.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. To use the first-event check feature, you must set the #first_check_id field in properties, and its type must be string.
TDPropertiesNode event_properties;
// first event
event_properties.SetString("#first_check_id", "first_event");
te.track_first("accountId", "distinctId", "eventName", event_properties);
Note: Because the first-event check is performed on the server, first events are stored with a 1-hour delay by default.
1.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.
// updatable event
std::string updateEventId = "update_001";
TDPropertiesNode update_event_properties;
update_event_properties.SetString("price", "100");
update_event_properties.SetString("status", "3");
// the value of "status" is 3, the value of "price" is 100
te.track_update("accountId", "distinctId", "eventName", updateEventId, update_event_properties);
TDPropertiesNode update_event_new_properties;
update_event_new_properties.SetString("status", "5");
// the value of "status" become 5, the value of "price" is still 100
te.track_update("accountId", "distinctId", "eventName", updateEventId, update_event_new_properties);
1.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.
// overwrite event
std::string overWriteEventId = "overWrite_001";
TDPropertiesNode overWrite_event_properties;
overWrite_event_properties.SetString("money", "99");
overWrite_event_properties.SetString("code", "10");
// the value of "code" is 10, the value of "money" is 99
te.track_overwrite("accountId", "distinctId", "eventName", overWriteEventId, overWrite_event_properties);
TDPropertiesNode overWrite_event_new_properties;
overWrite_event_new_properties.SetString("money", "66");
// The "money" has changed to 66，The "code" will be deleted
te.track_overwrite("accountId", "distinctId", "eventName", overWriteEventId, overWrite_event_new_properties);
2. User properties
The user property APIs supported by the AE platform are: user_set, user_setOnce, user_add, user_unset, user_del, user_append, and user_uniqAppend.
2.1 user_set
For general user properties, you can call user_set 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:
TDPropertiesNode userSet_properties;
userSet_properties.SetString("userName", "A");
// set user properties. the value of "userName" is "A"
te.user_set("accountId", "distinctId", userSet_properties);
userSet_properties.SetString("userName", "B");
// set user properties again，the value of "userName" will change to "B"
te.user_set("accountId", "distinctId", userSet_properties);
2.2 user_setOnce
If a user property only needs to be set once, you can call user_setOnce to set it. If the property already has a value, this call is ignored. The following example again sets the username:
// user_setOnce
TDPropertiesNode userSetOnce_properties;
userSetOnce_properties.SetString("user_one_name", "A");
// create "user_one_name" property, and the value is "A"
te.user_setOnce("accountId", "distinctId", userSetOnce_properties);
userSetOnce_properties.SetString("user_one_name", "B");
// the value of "user_one_name" is still "A"
te.user_setOnce("accountId", "distinctId", userSetOnce_properties);
2.3 user_add
To upload a numeric property, you can call user_add to accumulate its value. If the property hasn't 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:
// user_add
TDPropertiesNode userAdd_properties;
userAdd_properties.SetNumber("cash", 30);
// the value of "cash" is 30
te.user_add("accountId", "distinctId", userAdd_properties);
userAdd_properties.SetNumber("cash", 60);
// set user properties again，the value of "cash" is 90 now
te.user_add("accountId", "distinctId", userAdd_properties);
The property key is a string, and the Value can only be a number.
2.4 user_append
You can call user_append to append values to an array-type user property.
// user_append
TDPropertiesNode userAppend_properties;
std::vector<std::string> userAppendListValue;
userAppendListValue.push_back("11");
userAppendListValue.push_back("33");
userAppend_properties.SetList("arr1", userAppendListValue);
// the value of "arr1" is ["11", "33"]
te.user_append("accountId", "distinctId", userAppend_properties);
TDPropertiesNode userAppend_properties_new;
std::vector<std::string> userAppendListValueNew;
userAppendListValueNew.push_back("22");
userAppendListValueNew.push_back("33");
userAppend_properties_new.SetList("arr1", userAppendListValueNew);
// the value of "arr1" is ["11", "33", "22", "33"]
te.user_append("accountId", "distinctId", userAppend_properties_new);
2.5 user_uniqAppend
You can call user_uniqAppend to append values to an array-type user property. user_uniqAppend removes duplicates from the appended values, while user_append does not, so the user property may contain duplicates.
// user_uniqAppend
TDPropertiesNode userAppend_properties;
std::vector<std::string> userAppendListValue;
userAppendListValue.push_back("11");
userAppendListValue.push_back("33");
userAppend_properties.SetList("arr1", userAppendListValue);
// the value of "arr1" is ["11", "33"]
te.user_uniqAppend("accountId", "distinctId", userAppend_properties);
TDPropertiesNode userAppend_properties_new;
std::vector<std::string> userAppendListValueNew;
userAppendListValueNew.push_back("22");
userAppendListValueNew.push_back("33");
userAppend_properties_new.SetList("arr1", userAppendListValueNew);
// the value of "arr1" is ["11", "33", "22"]
te.user_uniqAppend("accountId", "distinctId", userAppend_properties_new);
2.6 user_unset
To clear the value of a user property, you can call user_unset to clear the specified property. If the property hasn't been created in the cluster yet, user_unset does not create it
// user_unset
TDPropertiesNode userUnset_properties;
userUnset_properties.SetNumber("userName", 0);
// the value of "userName" will be reset after executed "user_unset"
te.user_unset("accountId", "distinctId", userUnset_properties);
user_unset: The value passed in is the Key of the property to clear.
2.7 user_del
To delete a user, you can call user_del. After that, you can no longer query this user's user properties, but the events generated by the user can still be queried. This operation may have irreversible consequences, so use it with caution.
te.user_del("accountId", "distinctId");
3. Other features
3.1 BatchConsumer
When the data volume is too large or the network is abnormal, data may be lost. We don't recommend using it in the production environment
Transfers data to the AE server in batches in real time, without a transfer tool.
TDBatchConsumer batchConsumer("APPID","SERVER_URL", 10);
TDAnalytics te(batchConsumer, true);
Parameters:
-
APPID: The APPID of your project, which you can find on the Project Settings page in the AE backend -
SERVER_URL: The URL that data is uploaded to- If you use the cloud service, enter: https://global-receiver-ta.thinkingdata.cn
- If you use an on-premises deployment, bind a domain name to the data collection URL and configure an HTTPS certificate: https://your-domain-for-data-collection