Android

::: Tips

Before you begin, please read Preparation before Data Ingestion

The lowest system version required by Android SDK is Android 4.0 (API 14)

The size of Android SDK (aar format) is around 176 KB

:::

Latest version: 2.8.2

Update time: September 22, 2022

Resource download: AAR (opens new window),Source Code (opens new window)

1. SDK Integration

1.1 Automatic Integration

• Find build.gradle file under the Project, declare the mavenCentral repository:

buildscript {
    repositories {
        mavenCentral()
    }
}

• Find build.gradle file under the application , add the latest Android SDK package:

dependencies {
    implementation 'cn.thinkingdata.android:ThinkingAnalyticsSDK:2.8.2'
}

1.2 Manual Integration

1. Download and unzip Android SDK (opens new window)

2. Add ThinkingSDK.aar into a libs file folder

3. Add the following configuration should be added into build.gradle

dependencies {
    implementation fileTree(dir: 'libs', include: ['*.jar','*.aar'])
}

2. Initialization

//Initialize SDK in the main thread 
//Method 1
ThinkingAnalyticsSDK instance = ThinkingAnalyticsSDK.sharedInstance(this, APPID, SERVER_URL);
//Method 2
TDConfig config = TDConfig.getInstance(this, APPID, TA_SERVER_URL);
ThinkingAnalyticsSDK instance = ThinkingAnalyticsSDK.sharedInstance(config);

Instruction on parameters:

• APPID: The APPID of your project, which can be found on the project management page of TE.
• SERVER_URL:

  • If you are using a SaaS version, please check the receiver URL on this page

  • If you use the private deployment version, you can customize the data tracking URL .

Since Android 9.0+ restricts HTTP requests by default, please use HTTPS protocol only.

3. Common Features

We suggested that you read User identification rules before using common features; SDK would generate a random number that would be used as the distinct ID, and save the ID locally. Before the user logs in, the distinct ID would be used as the identification ID. Note: The distinct ID would change after the user reinstalled the App or use the APP with a new device.

3.1 Login

When the users log in , login could be called to set the account ID of the user. TE platform would use the account ID as the identification ID, and this ID would be saved before logout is called. The previous account ID would be replaced if login has been called multiple times.

// The login unique identifier of the user, corresponding to the #account_id in data tracking. #Account_id now is TE
instance.login("TE");

Login events wouldn't be uploaded in this method.

3.2 Super Properties

Super properties refer to properties that each event might have. You can call setSuperProperties to set super properties. It is recommended that you set super properties first before sending data. Some important properties (e.g., the membership class of users, source channels, etc.) should be set in each event. At this time, you can set these properties 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);//array object
        
        JSONArray  arr1    = new JSONArray();
        arr1.put("value");
        superProperties.put(arr1);//array
        //set super properties
        instance.setSuperProperties(superProperties);
    } catch (JSONException e) {
        e.printStackTrace();
    }

Super properties would be saved in local storage, and will not need to be called every time the App is opened. If the super properties set previously are uploaded after calling setSuperProperties, previous properties would be replaced.

• Key is the name of the property and refers to the string type. It must start with a character, and contain numbers, characters (insensitive to case, and upper cases would be transformed into lower cases by TE) and underscores "_", with a maximum length of 50 characters.
• Value, the value of the property, supports string, numbers, Boolean, time, object, array object, and array

The requirements for event properties and user properties are the same with that for super properties

3.3 Automatically Track Events

The following code is an example of tracking installation, open_app and close_app events. To get more information about the automatic tracking of SDK, please refer to the Detailed introduction of automatic tracking function

List<ThinkingAnalyticsSDK.AutoTrackEventType> eventTypeList = new ArrayList<>();
//APP install event
eventTypeList.add(ThinkingAnalyticsSDK.AutoTrackEventType.APP_INSTALL);
//APP start event
eventTypeList.add(ThinkingAnalyticsSDK.AutoTrackEventType.APP_START);
//APP end event
eventTypeList.add(ThinkingAnalyticsSDK.AutoTrackEventType.APP_END);
//enable autotrack event
ThinkingAnalyticsSDK.sharedInstance(this, TE_APP_ID).enableAutoTrack(eventTypeList);

3.4 Sending Events

You can call track to upload events. It is suggested that you set event properties based on the data tracking plan drafted previously. Here is an example of a user buying an item:

try {
    JSONObject properties = new JSONObject();
    properties.put("product_name","product name");
    instance.track("product_buy",properties);
} catch (JSONException e) {
    e.printStackTrace();
}

The event name is string type. It could only start with a character and could contain figures, characters, and an underline "_", with a maximum length of 50 characters.

3.5 User Properties

You can set general user properties by calling user_set API. The original properties would be replaced by the properties uploaded via this API. The data type of newly-created user properties must be the same as the uploaded properties. User name setting is taken as the example here:

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

4. Best Practice

The following sample code covers all the above-mentioned operations. It is recommended that the SDK be used in the following steps:

ThinkingAnalyticsSDK instance;
if (privacy policy is authorized) {
    instance = ThinkingAnalyticsSDK.sharedInstance(this, TE_APP_ID, TE_SERVER_URL);
    if（instance != null）
    {
      //if the user has logged in, the account ID of the user could be set as the unique identifier 
      instance.login("TE");
      //After setting super properties, each event would have super properties
      try {
        JSONObject superProperties = new JSONObject();
        superProperties.put("channel","te");//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);//array object
        
        JSONArray  arr1    = new JSONArray();
        arr1.put("value");
        superProperties.put(arr1);//array
        //set super properties
        instance.setSuperProperties(superProperties);
      } catch (JSONException e) {
        e.printStackTrace();
      }
    
      //Enable auto-tracking
      List<ThinkingAnalyticsSDK.AutoTrackEventType> eventTypeList = new ArrayList<>();
      eventTypeList.add(ThinkingAnalyticsSDK.AutoTrackEventType.APP_INSTALL);
      eventTypeList.add(ThinkingAnalyticsSDK.AutoTrackEventType.APP_START);
      eventTypeList.add(ThinkingAnalyticsSDK.AutoTrackEventType.APP_END);
      instance.enableAutoTrack(eventTypeList);
      
      //upload events
      try {
       JSONObject properties = new JSONObject();
       properties.put("product_name","product name");
       instance.track("product_buy",properties);
      } catch (JSONException e) {
       e.printStackTrace();
      }
  
      //Set user properties
      try {
        JSONObject userProperties = new JSONObject();
        userProperties.put("username","TE");
        instance.user_set(userProperties);
       } catch (JSONException e) {
         e.printStackTrace();
       }
    }
}