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_instance 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 viewing a product:
%% Note: at least one of account_id and distinct_id must be set
%% Set the user's IP address. The AE system parses the user's geographic location from the IP address. If it isn't set, it isn't reported by default
%% Set the time when the event occurred. If it isn't set, the current time is used by default. Note: #time must be of the timestamp() type
%% Report an event
td_analytics:track_instance(TE_SDK, "account_id_Erlang", "distinct_logbus", "ViewProduct", #{"#ip" => "192.168.1.1", "#time" => os:timestamp(), "key_1" => "🚓🦽🦼🚲🚜🚜🦽", "key_2" => 2.2, "key_array" => ["🚌", "🏍", "😚😊"]}),
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.
FirstCheckId = "first_check_id",
%% First event
td_analytics:track_first_instance(TE_SDK, "account_id_Erlang", "distinct_id", "first_login", FirstCheckId, #{"key1" => "value1", "key2" => "value2"}),
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.
EventName = "event_name",
EventId = "event_id",
%% After reporting, the event property status is 3 and price is 100
td_analytics:track_update_instance(TE_SDK, "account_id_Erlang", "distinct_id", EventName, EventId, #{"price" => 100, "status" => 3}),
%% After reporting, the event property status is 5 and price stays 100
td_analytics:track_update_instance(TE_SDK, "account_id_Erlang", "distinct_id", EventName, EventId, #{"status" => 5}),
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.
EventName = "overWrite_event",
EventId = "event_id",
%% After reporting, the event property price is 100 and status is 5
td_analytics:track_overwrite_instance(TE_SDK, "account_id_Erlang", "distinct_id", EventName, EventId, #{"price" => 100, "status" => 5}),
%% After reporting, the event property price is 20 and the status property is deleted
td_analytics:track_overwrite_instance(TE_SDK, "account_id_Erlang", "distinct_id", EventName, EventId, #{"price" => 20}),
2. User properties
The user property APIs supported by the AE platform are: user_set_instance, user_set_once_instance, user_add_instance, user_unset_instance, user_del_instance, user_append_instance, and user_unique_append_instance.
2.1 user_set_instance
For general user properties, you can call user_set_instance to set them. Properties uploaded through this API overwrite the original property values. If the user property doesn't exist yet, a new user property is created with the same type as the value passed in. The following example sets the username:
%% "name" is "A"
td_analytics:user_set_instance(TE_SDK, "account_id", "distinct_id", #{"name" => "A", "abc" => ["a", "b", "c"]}),
%% "name" is "B"
td_analytics:user_set_instance(TE_SDK, "account_id", "distinct_id", #{"name" => "B", "abc" => ["a", "b", "c"]}),
2.2 user_set_once_instance
If a user property only needs to be set once, you can call user_set_once_instance to set it. If the property already has a value, this record is ignored. Again, take setting the username as an example:
%% "name" is "A"
td_analytics:user_set_once_instance(TE_SDK, "account_id", "distinct_id", #{"name" => "A"}),
%% "name" is still "A"
td_analytics:user_set_once_instance(TE_SDK, "account_id", "distinct_id", #{"name" => "B"}),
2.3 user_add_instance
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:
%% "amount" is 30
td_analytics:user_add_instance(TE_SDK, "account_id", "distinct_id", #{"amount" => 30}),
%% "amount" is 90
td_analytics:user_add_instance(TE_SDK, "account_id", "distinct_id", #{"amount" => 60}),
The property key is a string, and the Value can only be a number.
2.4 user_append_instance
You can call user_append_instance to append values to a user property of the array type.
%% "array" is ["arr1", "arr3"]
td_analytics:user_append_instance(TE_SDK, "account_id", "distinct_id", #{"array" => ["arr1", "arr3"]}),
%% "array" is ["arr1", "arr3", "arr2", "arr3"]
td_analytics:user_append_instance(TE_SDK, "account_id", "distinct_id", #{"array" => ["arr2", "arr3"]}),
2.5 user_unique_append_instance
You can call user_unique_append_instance to append values to a user property of the array type. user_unique_append_instance deduplicates the appended user property values, whereas user_append_instance doesn't, so the user property may contain duplicates.
%% "array" is ["arr1", "arr3"]
td_analytics:user_unique_append_instance(TE_SDK, "account_id", "distinct_id", #{"array" => ["arr1", "arr3"]}),
%% "array" is ["arr1", "arr3", "arr2"]
td_analytics:user_unique_append_instance(TE_SDK, "account_id", "distinct_id", #{"array" => ["arr2", "arr3"]}),
2.6 user_unset_instance
To clear the value of a user property, you can call user_unset_instance to clear the specified property. If the property hasn't been created in the cluster, user_unset_instance doesn't create it
td_analytics:user_unset_instance(TE_SDK, "account_id", "distinct_id", ["age", "abc"]),
The value passed to user_unset_instance is the key of the property to be cleared.
2.7 user_del_instance
To delete a user, you can call user_del_instance. After that, you can no longer query the 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
td_analytics:user_del_instance(TE_SDK, "account_id", "distinct_id"),