Golang

Last updated 10/03/2026

tip

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

Latest version: v2.3.0

Update time: 2026-03-17

Downloads: Source code

Note

This document applies to v2.0.0 and later. For earlier versions, see Go SDK integration guide (V1)

1. Integrate the SDK

1. We provide two options for integrating the SDK:

Option 1: Run the following command to get the latest Golang SDK

# Get the SDK
go get github.com/ThinkingDataAnalytics/go-sdk/v2

# Update the SDK
go get -u github.com/ThinkingDataAnalytics/go-sdk/v2

Option 2: Module mode

//Import thinkingdata at the beginning of the code file
import "github.com/ThinkingDataAnalytics/go-sdk/v2/src/thinkingdata"

# Pull the latest SDK module
go mod tidy

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

The following sample code initializes the SDK:

// Create the LogConfig configuration
config := thinkingdata.TDLogConsumerConfig {
    FileNamePrefix: "test_prefix", // log file prefix
    Directory: "LOG_DIRECTORY", // File path for event collection
}
// Initialize logConsumer
consumer, _ := thinkingdata.NewLogConsumerWithConfig(config)
// Create the te object
te := thinkingdata.New(consumer)

LOG_DIRECTORY is the path of the local folder that data is written to. Set the folder that LogBus monitors to this path, and LogBus will monitor and upload the data

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:

accountId := "te_account_id"
distinctId := "te_distinct_id"//accountId and distinctId can't both be empty
properties := map[string]interface{}{
   //Set the user's IP address. The AE system parses the user's geographic location from the IP address
   "#ip":       "123.123.123.123",
   "channel":   "te",       // String
   "age":       1,          // Number
   "is_success": true,       // Boolean
   "birthday":  time.Now(), // Time
   // Object
   "object": map[string]interface{}{
      "key": "value",
   }, 
   //Object group
   "objectArr": []interface{}{
      map[string]interface{}{
         "key": "value",
      },
   },
   "arr":     []string{"value"}, // Array
}
// Track the event
err := te.Track(accountId, distinctId, "payment", properties)

• 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 original property values. If the user property doesn't exist yet, it is created with the same type as the passed-in property. The following example sets the user name:

// username is now TA
err := te.UserSet("accountId", "distinctId", map[string]interface{}{
   "user_name": "TA",
})
// username is now AE
err = te.UserSet("accountId", "distinctId", map[string]interface{}{
   "user_name": "AE",
})

3.3 Send data

When you use TDLogConsumer, the SDK writes the collected data to disk in real time.

The Flush() method of the TDAnalytics object syncs the file system's default memory cache to disk in real time. You generally don't need to call Flush() manually.

3.4 Shut down the SDK

// Close and exit the SDK
te.Close()

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:

// Create the LogConfig configuration
config := thinkingdata.TDLogConsumerConfig {
    Directory: "./log_directory", // File path for event collection
}
// Initialize logConsumer
consumer, _ := thinkingdata.NewLogConsumerWithConfig(config)
// Create the te object
te := thinkingdata.New(consumer)

accountId := "te_account_id"
distinctId := "te_distinct_id"//accountId and distinctId can't both be empty
properties := map[string]interface{}{
    //Set the user's IP address. The AE system parses the user's geographic location from the IP address
    "#ip":       "123.123.123.123",
    "channel":   "te",       // String
    "age":       1,          // Number
    "isSuccess": true,       // Boolean
    "birthday":  time.Now(), // Time
    // Object
    "object": map[string]interface{}{
       "key": "value",
    },
    //Object group
    "objectArr": []interface{}{
       map[string]interface{}{
          "key": "value",
       },
    },
    "arr":     []string{"value"}, // Array
}
// Upload the event
err := te.Track(accountId, distinctId, "payment", properties)
if err != nil {
    fmt.Println(err)
}
//Set user properties
err = te.UserSet("accountId", "distinctId", map[string]interface{}{
    "user_name": "AE",
})
if err != nil {
    fmt.Println(err)
}