C#
Before you integrate the SDK, read Pre-integration preparation.
Latest version: v2.0.3
Update time: 2025-09-03
Downloads: Source code
This document applies to v2.0.0 and later. For earlier versions, see C# SDK Integration Guide (V1)
1. Integrate the SDK
Option 1: Integrate with NuGet
- Search for the ThinkingDataAnalytics library in NuGet and install it in your project
- The ThinkingDataAnalytics library also installs the Newtonsoft.Json library automatically
Option 2: Integrate the dll file
- Download the SDK source code
- Open the solution in the source code and build the SDK dll file manually
- Add the ThinkingDataAnalytics SDK dll file to your project
- The SDK depends on the Newtonsoft.Json framework for JSON parsing. Manually add the Newtonsoft.Json library to your project.
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:
using ThinkingData.Analytics
TDAnalytics te = new TDAnalytics(new TDLoggerConsumer("LOG_DIRECTORY"));
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 monitors and uploads 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:
Dictionary<string, object> properties = new Dictionary<string, object>();
// Set the user's IP address. The AE system resolves the user's geographic location from the IP address
properties.Add("#ip", "123.123.123.123");
//Set event properties
properties.Add("channel", "TE");//String
properties.Add("age", 1);//Number
properties.Add("is_success", true);//Boolean value
List<string> list = new List<string>();
list.Add("value");
properties.Add("array", list);//Array
//Object
Dictionary<string, Object> objectTest = new Dictionary<string, object>();
objectTest.Add("key", "value");
properties.Add("object", objectTest);
//Object group
List<Object> object_arr = new List<Object>();
object_arr.Add(objectTest);
properties.Add("object_arr", object_arr);
//Report an event with custom properties; at least one of accountId and distinctId must not be empty
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 values. If the user property doesn't exist yet, it is created with the same type as the value passed in. The following example sets the username:
//username is now TA
Dictionary<string, object> properties= new Dictionary<string, object>();
properties.Add("user_name","TA");
te.UserSet("accountId","distinctId", properties);
//userName is now AE
Dictionary<string, object> newProperties= new Dictionary<string, object>();
newProperties.Add("user_name","TE");
//Set user properties; set at least one of accountId and distinctId
te.UserSet("accountId","distinctId", newProperties);
3.3 Send data
When you use TDLoggerConsumer, collected events are first encoded as JSON strings and added to a cache string. Data is written to disk only when the length of the cache string exceeds the configured length. The default maximum length is 8192.
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
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:
using ThinkingData.Analytics;
//Initialize the SDK
TDAnalytics te = new TDAnalytics(new TDLoggerConsumer("LOG_DIRECTORY"));
Dictionary<string, object> properties = new Dictionary<string, object>();
// Set the user's IP address. The AE system resolves the user's geographic location from the IP address
properties.Add("#ip", "123.123.123.123");
//Set event properties
properties.Add("channel", "TE");//String
properties.Add("age", 1);//Number
properties.Add("is_success", true);//Boolean value
List<string> list = new List<string>();
list.Add("value");
properties.Add("array", list);//Array
Dictionary<string, Object> objectTest = new Dictionary<string, object>();
objectTest.Add("key", "value");
properties.Add("object", objectTest);
//Object group
List<Object> object_arr = new List<Object>();
object_arr.Add(objectTest);
properties.Add("object_arr", object_arr);
//Report an event with custom properties; at least one of accountId and distinctId must not be empty
te.Track("accountId", "distinctId", "Payment", properties);
//username is now TA
Dictionary<string, object> userProperties = new Dictionary<string, object>();
userProperties.Add("user_name", "TA");
te.UserSet("accountId", "distinctId", userProperties);
//Calling flush writes data to the file immediately. In production, avoid calling flush frequently, which can cause IO or network overhead
te.Flush();