Skip to main content

Advanced guide

Last updated 10/05/2026

1. Set user IDs​

By default, the SDK instance uses a random number as each user's 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 clears the cache or switches devices.

1.1 Set the distinct ID​

tip

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 your app has its own distinct ID management system for each user, you can call setDistinctId to set the distinct ID:

// Set the distinct ID to Thinker
TDAnalytics.setDistinctId("Thinker");

To get the current distinct ID, call getDistinctId:

//Return the distinct ID
TDAnalytics.getDistinctId();

If you need to set it, you must call this API before initialization

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
TDAnalytics.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.

// Remove "#account_id" from the reported data. Subsequent data will not carry "#account_id"
TDAnalytics.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 that you set the event properties and the conditions for sending events based on the document you prepared earlier. The following example uses a user purchasing a product

TDAnalytics.track("product_buy", // Event name
    {
        product_name: "Product Name"
    } //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.

TDAnalytics.trackFirst("device_activation",{ key: "value" });

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
TDAnalytics.trackFirst("account_activation",{ key: "value" },"TA");

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
TDAnalytics.trackUpdate("UPDATABLE_EVENT",{ status: 3, price: 100 },"test_event_id");

// After reporting, the event property status is updated to 5 and price is unchanged
TDAnalytics.trackUpdate("UPDATABLE_EVENT",{ status: 5 },"test_event_id");

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
TDAnalytics.trackOverwrite("OVERWRITE_EVENT",{ status: 3, price: 100 },"test_event_id");

// After reporting, the event property status is updated to 5 and the price property is deleted
TDAnalytics.trackOverwrite("OVERWRITE_EVENT",{ status: 5 },"test_event_id");

2.5 Super properties​

Some important properties, such as the user's device ID, source channel, and user status, need to be set in every event. In this case, you can set them as super properties, which are carried by every event. We recommend that you set super properties before sending events.

There are two types of super properties: static super properties and dynamic super properties. When an event is reported, super properties are inserted into the properties of the data. If a super property has the same key as a custom property set in the event, the value is determined by the following priority: Custom properties > Dynamic super properties > Static super properties > Preset properties.

2.5.1 Static super properties​

Some important properties, such as the user's channel, nickname, and ID, need to be set in every event. You can call setSuperProperties to set static super properties, which take effect globally. When caching is enabled (it is enabled by default), static super properties are cached and still take effect the next time the app starts.

The parameter of static super properties is a JSON object, and its format requirements are the same as those of event properties.

// Set super properties. All data events will carry these properties
TDAnalytics.setSuperProperties({
     channel: "Channel Name",
     user_name: "User Name"
});

In addition to setting properties, we also provide other APIs for working with static super properties to meet day-to-day business needs.

// Get static super properties
TDAnalytics.getSuperProperties();
// Clear one static super property, for example, the previously set 'channel' property. Subsequent data will not carry this property
TDAnalytics.unsetSuperProperty("channel");
// Clear all static super properties
TDAnalytics.clearSuperProperties();

2.5.2 Dynamic super properties​

Use setDynamicSuperProperties to set the callback function for dynamic super properties. The SDK triggers the callback function when an event is reported and adds the returned JSON object to the event properties. The parameter of setDynamicSuperProperties is a function, and the function must return a JSON object.

// Set dynamic super properties. The callback function is triggered when an event is reported, and the returned JSON object is added to the event properties
TDAnalytics.setDynamicSuperProperties(function() {
    var d = new Date();
    d.setHours(10);
    return { date: d };
});

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
TDAnalytics.timeEvent("stay_shop");
/**do someting
    .......
**/
//The user leaves the product page and timing ends. The "stay_shop" event will carry the #duration property that indicates the event duration
TDAnalytics.track("stay_shop",{product_name:"Product Name"});

3. User properties​

The user property APIs 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 existing property values. If the user property does not exist yet, it is created with the same type as the value passed in. The following example sets the user name:

// username is now TA
TDAnalytics.userSet({
    username: "TA" 
});
//username is now AE
TDAnalytics.userSet({
    username: "AE" 
});

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
TDAnalytics.userSetOnce({
    first_payment_time: "2018-01-01 01:23:45.678" 
});
//first_payment_time is still 2018-01-01 01:23:45.678
TDAnalytics.userSetOnce({
    first_payment_time: "2018-12-31 01:23:45.678" 
});

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. Passing a negative value is equivalent to subtraction.

//total_revenue is now 30
TDAnalytics.userAdd({
    total_revenue: 30
});
//total_revenue is now 678
TDAnalytics.userAdd({
    total_revenue: 648
});

3.4 userUnset​

To clear a user's user property value, you can call userUnset to clear the specified property. If the property has not yet been created in the cluster, userUnset does not create it.

// Clear the value of the user property named userPropertykey for this user, that is, set it to NULL
TDAnalytics.userUnset("userPropertykey");

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.

TDAnalytics.userDelete();

3.6 userAppend​

You can call userAppend to append elements to user data of the array type.

TDAnalytics.userAppend({
    user_list: ["apple", "ball"]
});

3.7 userUniqAppend​

You can call userUniqAppend to append unique elements to user data of the Array (List) type. userUniqAppend deduplicates the appended user property values, while userAppend does not, so the user property may contain duplicates.

//The value of user_list is now ["apple", "ball"]
TDAnalytics.userAppend({
    user_list: ["apple", "ball"]
});
//The value of user_list is now ["apple","apple","ball","cube"]
TDAnalytics.userAppend({
    user_list: ["apple", "cube"]
});
//The value of user_list is now ["apple", "ball","cube"]
TDAnalytics.userUniqAppend({
    user_list: ["apple", "cube"]
});

4. Encryption​

The SDK supports encryption. The client encrypts data with AES + RSA, and the server then decrypts it. Encryption and decryption require cooperation between the client and the server. For details, contact your customer success representative.

Set the enableEncrypt property to true, and set the default version number and public key.

var config = {
  appId: "YOUR_APP_ID", // Project APP ID
  serverUrl: "YOUR_SERVER_URL", // Reporting URL
  enableEncrypt: true, // Enable encryption for data transmission
  secretKey: {
    publicKey:'YOUR_PUBLIC_KEY', // Public key for encryption
    version:0 // Key version number
   }
};
// Initialize
TDAnalytics.init(config);

5. Other features​

5.1 Get the device ID​

You can call getDeviceId() to get the device ID.

TDAnalytics.getDeviceId();

The device ID is saved in the cache. If the user clears the cache, the device ID is reset.

5.2 Set up event cache reporting​

You can enable event cache reporting during initialization. This is currently supported only on uni-app. On Android, iOS, and HarmonyOS, cached batch reporting is used by default and cannot be configured separately.

// AE SDK configuration object
var config = {
  appId: "YOU-APP-ID", // APP ID of the project
  serverUrl: "https://youserverurl.com", // Data reporting URL
  enableBatch: true, // Whether to enable batch reporting of cached events. true = enabled, false = disabled
  batchConfig: {
    size: 5, // Number of cached events per report
    interval: 5000 // Reporting interval for cached events (milliseconds)
  }
};
// Initialize
TDAnalytics.init(config);

5.3 Set the default time zone​

By default, the SDK reports the local time at which the API is called as the event time. Starting from v3.0.3, you can also set a default time zone during initialization so that the time of all events is aligned to the time zone you set:

var config = {
  appId: "YOU-APP-ID", // Project APP ID
  serverUrl: "https://youserverurl.com", // Data reporting URL
  zoneOffset:8
};

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.

Was this page helpful?
On this page