Skip to main content

Java

Last updated 10/03/2026
tip

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

The Java SDK requires JDK 8 or later

Latest version: v3.0.4-beta.1

Update time: 2026-01-07

Downloads: Source code

Note

This document applies to v3.0.0 and later. For earlier versions, see Java SDK integration guide (V2)

The SDK APIs are thread-safe and are called synchronously by default. When you report a large volume of data, you can call the APIs in a child thread to avoid affecting your business threads.

1. Integrate the SDK​

1. To integrate the SDK with Maven, add the following dependency to the pom.xml file:

<dependencies>
    // others...
    <dependency>
        <groupId>cn.thinkingdata</groupId>
        <artifactId>thinkingdatasdk</artifactId>
        <version>3.0.2</version>
    </dependency>
</dependencies>

2. Install LogBus

We recommend using SDK + LogBus to collect and report server-side data. To install Logbus, see the following document: LogBus user guide

2. Initialization​

Method 1​

TDAnalytics te = new TDAnalytics(new TDLoggerConsumer("LOG_DIRECTORY"), false);

LOG_DIRECTORY is the path of the folder that data is written to.

Method 2​

The SDK can be initialized with a configuration object, which gives you fine-grained control over SDK features. For example, you can add a prefix to log files.

TDLoggerConsumer.Config config = new TDLoggerConsumer.Config("LOG_DIRECTORY");
config.setFilenamePrefix("unique_name");
TDAnalytics te = new TDAnalytics(new TDLoggerConsumer(config), false);

3. Common features​

To make sure that the distinct ID and account ID can be bound correctly, if your game uses both the distinct ID and the account ID, we strongly recommend that you upload both IDs. Otherwise, accounts may fail to match and users may be counted more than once. For details on ID binding rules, see User identification rules.

3.1 Send events​

You can call track to upload events. We recommend setting event properties and the conditions for sending events based on the document you prepared earlier. The following sample code sends an event:

//Set event properties
HashMap<String,Object> properties = new HashMap<>();
// Set the user's IP address. The AE system parses the user's geographic location from the IP address
properties.put("#ip", "192.168.1.1");//String
properties.put("channel","te");//String
properties.put("age",1);//Number
properties.put("isSuccess",true);//Boolean
properties.put("birthday",new Date());//Time

HashMap<String,Object>  object = new HashMap<>();
object.put("key", "value");
properties.put("object",object);//Object

HashMap<String,Object> object1 = new HashMap<>();
object1.put("key", "value");

ArrayList<Object> arr = new ArrayList<>();
arr.add(object1);
properties.put("object_arr",arr);//Object group

ArrayList<String> arr1 = new ArrayList<>();
arr1.add("value");
properties.put("arr",arr1);//Array

try {
    te.track("account_id","distinct_id","payment",properties);
} catch (Exception e) {
    System.out.println("except:"+e);
}
  • 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.
  • Key is the name of the property and is of string type. It must start with a letter, can contain digits, letters, and underscores "_", can be up to 50 characters long, and is case-insensitive. AE converts it to lowercase
  • Value is the value of the property. Supported types are string, number, Boolean, time, object, object group, and array

User properties have the same requirements as event properties

3.2 Set user properties​

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 did not exist before, it is created with the same type as the value passed in. The following example sets the user name:

//user_name is now TA
Map<String,Object> userProperties = new HashMap<String,Object>();
userProperties.put("user_name", "TA");
try {
   te.userSet("account_id","distinct_id",userProperties);
} catch (Exception e) {
  System.out.println("except:"+e);
}
 
//user_name is now AE
Map<String,Object> newUserProperties = new HashMap<String,Object>();
newUserProperties.put("user_name", "AE");
try {
   te.userSet("account_id","distinct_id",newUserProperties);
} catch (Exception e) {
  System.out.println("except:"+e);
}

3.3 Send data​

When you use TDLogConsumer, collected events are first encoded as JSON strings and added to a buffer. Data is written to disk only when the length of the strings in the buffer exceeds the configured length. The default maximum length is 8192 bytes.

In some business scenarios, if you want data to be reported to the AE server immediately, you can call flush(). Note that calling flush() frequently degrades service performance.

te.flush();

3.4 Shut down the SDK​

try{
   te.close();
} catch (Exception e) {
    System.out.println("except:"+e);
}

Shuts down and exits the SDK. Call this API before you shut down the server to avoid losing data in the cache

4. Best practices​

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

//Initialize the SDK. LOG_DIRECTORY is the path of the local folder that data is written to
TDAnalytics te = new TDAnalytics(new TDLoggerConsumer("LOG_DIRECTORY"), false);

//Set event properties
HashMap<String,Object> properties = new HashMap<>();
// Set the user's IP address. The AE system parses the user's geographic location from the IP address
properties.put("#ip", "192.168.1.1");//String
properties.put("channel","te");//String
properties.put("age",1);//Number
properties.put("isSuccess",true);//Boolean
properties.put("birthday",new Date());//Time

HashMap<String,Object>  object = new HashMap<>();
object.put("key", "value");
properties.put("object",object);//Object

HashMap<String,Object> object1 = new HashMap<>();
object1.put("key", "value");

ArrayList<Object> arr = new ArrayList<>();
arr.add(object1);
properties.put("object_arr",arr);//Object group

ArrayList<String> arr1 = new ArrayList<>();
arr1.add("value");
properties.put("arr",arr1);//Array

try {
    te.track("account_id","distinct_id","payment",properties);
} catch (Exception e) {
    System.out.println("except:"+e);
}

//Set user properties
Map<String,Object> userProperties = new HashMap<String,Object>();
userProperties.put("user_name", "TE");
try {
   te.userSet("account_id","distinct_id",userProperties);
} catch (Exception e) {
  System.out.println("except:"+e);
}
Was this page helpful?
On this page