Skip to main content

Android

Last updated 10/03/2026
tip

Before you integrate the SDK, read Pre-integration preparation.

The Android SDK requires Android 4.0 (API 14) or later.

The Android SDK (aar format) is about 200 KB in size.

SDK name: ThinkingData SDK

Developer: 数数信息科技(上海)有限公司

Version: 3.5.0

Features: The SDK collects client logs in the form of events and user properties, and supports analysis of daily active users, usage duration, retention, and other behaviors.

Privacy statement: ThinkingData SDK Privacy Statement

Latest version: 3.5.0

Update time: 2026-08-19

Downloads: Source code Download

Note

This document applies to v3.0.0 and later. For earlier versions, see Android Integration Guide (V2) and SDK download (V2).

1. Integrate the SDK​

1.1 Automatic integration​

  • Add the following dependency configuration to the build.gradle file at the Project level
buildscript {
    repositories {
        jcenter()
        mavenCentral()
    }
}
  • Add the dependency to the build.gradle file in the Module directory:
dependencies {
    implementation 'cn.thinkingdata.android:ThinkingAnalyticsSDK:3.5.0'
}

1.2 Manual integration​

  1. Download and unzip the Android SDK
  2. Add TDAnalytics.aar and TDCore.aar to the libs folder in the Module directory
  3. Add the following configuration to build.gradle in the Module directory
dependencies {
    implementation fileTree(dir: 'libs', include: ['*.jar','*.aar'])
}

2. Initialization​

// Initialize the SDK on the main thread
//Method 1
TDAnalytics.init(this, APPID, SERVER_URL);
//Method 2
TDConfig config = TDConfig.getInstance(this, APPID, TE_SERVER_URL);
TDAnalytics.init(config);

Parameters:

  • APPID: The APPID of your project, which you can find on the Project Settings page in AE

  • SERVER_URL: The URL that data is uploaded to

    • If you use the cloud service, view the Data Receiving URL in Project Settings -> Implementation.
    • If you use an on-premises deployment, you can customize the data collection URL.

Android 9.0 and later restrict HTTP requests by default, so make sure you use HTTPS.

3. Common features​

Before you use the common features, we recommend that you read the user identification rules. By default, the SDK generates a random number as the distinct ID and stores it locally. Before a user logs in, the distinct ID is used as the user's identifier. Note: The distinct ID changes when the user reinstalls the app or switches devices.

3.1 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

3.2 Set super properties​

Super properties are properties that every event carries. You can call setSuperProperties to set super properties. We recommend setting super properties before you send events. Some important properties, such as a user's membership level and source channel, need to be set in every event; in this case, you can set them as super properties.

try {
        JSONObject superProperties = new JSONObject();
        superProperties.put("channel","ta");//String
        superProperties.put("age",1);//Number
        superProperties.put("isSuccess",true);//Boolean
        superProperties.put("birthday",new Date());//Time

        JSONObject object = new JSONObject();
        object.put("key", "value");
        superProperties.put("object",object);//Object

        JSONObject object1 = new JSONObject();
        object1.put("key", "value");
        JSONArray  arr    = new JSONArray();
        arr.put(object1);
        superProperties.put("object_arr",arr);//Object group

        JSONArray  arr1    = new JSONArray();
        arr1.put("value");
        superProperties.put("arr",arr1);//Array
        //Set super properties
        TDAnalytics.setSuperProperties(superProperties);
    } catch (JSONException e) {
        e.printStackTrace();
    }

Super properties are saved in the cache, so you don't need to call this every time the app starts. If you call setSuperProperties to upload a super property that was set before, the new value overwrites the previous one.

  • Key is the name of the property and is of the string type. It must start with a letter, can contain only digits, letters, and underscores "_", and can be up to 50 characters long. Keys are not case-sensitive; AE converts all letters to lowercase
  • Value is the value of the property. Supported types are string, number, Boolean, time, object, object group, and array

Event properties and user properties have the same requirements as super properties

3.3 Enable auto-tracking​

The following code example enables the install, start, and end events. To learn more about the SDK's auto-tracking capabilities, see Auto-tracked events

//TDAnalytics.TDAutoTrackEventType.APP_INSTALL  App install event
//TDAnalytics.TDAutoTrackEventType.APP_START App start event
//TDAnalytics.TDAutoTrackEventType.APP_END  App end event

//Enable auto-tracked events
TDAnalytics.enableAutoTrack(TDAnalytics.TDAutoTrackEventType.APP_START | TDAnalytics.TDAutoTrackEventType.APP_END
        | TDAnalytics.TDAutoTrackEventType.APP_INSTALL);

3.4 Send events​

You can call track to upload events. We recommend setting event properties according to the tracking plan you prepared earlier. The following example tracks a user purchasing a product:

try {
    JSONObject properties = new JSONObject();
    properties.put("product_name","Product Name");
    TDAnalytics.track("product_buy", properties);
} catch (JSONException e) {
    e.printStackTrace();
}

The event name is of the string type. It must start with a letter, can contain digits, letters, and underscores "_", and can be up to 50 characters long.

3.5 Set user properties​

For general user properties, you can call userSet 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:

try {
    //username is now TA
    JSONObject properties = new JSONObject();
    properties.put("username","TA");
    TDAnalytics.userSet(properties);
    //userName is now AE
    JSONObject newProperties = new JSONObject();
    newProperties.put("username","TE");
    TDAnalytics.userSet(newProperties);
} catch (JSONException e) {
    e.printStackTrace();
}

4. Best practices​

The following sample code includes all of the operations above. We recommend using them in the following order:

if (isPrivacyPolicyAccepted) { // The user has accepted the Privacy Policy
    TDAnalytics.init(this, APPID, SERVER_URL);
    
    //Enable auto-tracked events
    TDAnalytics.enableAutoTrack(TDAnalytics.TDAutoTrackEventType.APP_START | TDAnalytics.TDAutoTrackEventType.APP_END
        | TDAnalytics.TDAutoTrackEventType.APP_INSTALL);
        
    //If the user has logged in, you can set the user's account ID as the unique identifier
    TDAnalytics.login("TA");
    //After super properties are set, every event carries them
    try {
    JSONObject superProperties = new JSONObject();
    superProperties.put("channel","ta");//String
    superProperties.put("age",1);//Number
    superProperties.put("isSuccess",true);//Boolean
    superProperties.put("birthday",new Date());//Time
    
    JSONObject object = new JSONObject();
    object.put("key", "value");
    superProperties.put("object",object);//Object
    
    JSONObject object1 = new JSONObject();
    object1.put("key", "value");
    JSONArray  arr    = new JSONArray();
    arr.put(object1);
    superProperties.put("object_arr",arr);//Object group
    
    JSONArray  arr1    = new JSONArray();
    arr1.put("value");
    superProperties.put("arr",arr1);//Array
    //Set super properties
    TDAnalytics.setSuperProperties(superProperties);
    } catch (JSONException e) {
    e.printStackTrace();
    }
        
    //Send an event
    try {
    JSONObject properties = new JSONObject();
    properties.put("product_name","Product Name");
    TDAnalytics.track("product_buy", properties);
    } catch (JSONException e) {
    e.printStackTrace();
    }
    
    //Set user properties
    try {
    JSONObject userProperties = new JSONObject();
    userProperties.put("username","TA");
    TDAnalytics.userSet(userProperties);
    } catch (JSONException e) {
     e.printStackTrace();
    }
}
Was this page helpful?
On this page