# C #SDK User Guide
This guide will show you how to use the C #SDK to access your project. You can access the source code of the C #SDK in GitHub (opens new window).
**The latest version is **: 1.3.1
**Updated **: 2021-04-22
C #SDK download address (opens new window)
# I. Integrate and Initialize SDK
# 1.1 Integrate SDK
The C #SDK is used at the server level . NET Framework
application, download the SDK file (opens new window), extract the dll file can be referenced.
Add the following code to the header to introduce the SDK:
using ThinkingData.Analytics
# 1.2 Initialize SDK
You can get an SDK instance in three ways:
**(1) LoggerConsumer: **write local files in batches in real time. The default is separated by days. It needs to be used with LogBus for data upload. It is recommended to use**.**
//Default split file by day
ThinkingdataAnalytics ta = new ThinkingdataAnalytics(new LoggerConsumer(logDirectory));
//If you want to split files by hour, you can initialize them as follows
// ThinkingdataAnalytics ta = new ThinkingdataAnalytics(new LoggerConsumer(logDirectory,LoggerConsumer.RotateMode.HOURLY));//按小时切分,无大小切分
// Call SDK...
// Report Data
ta.Track(accountId, distinctId, "Payment", properties);
// Call SDK...
// Closing interface needs to be called before server is closed
ta.Close();
The incoming parameter is the local folder address written to. You only need to set the listening folder address of LogBus to the address here, and you can use LogBus to monitor and upload data.
**(2) BatchConsumer: **batch real-time data transmission to the server, do not need to match the transmission tool, there is a risk of data loss, please use carefully**.**
ThinkingdataAnalytics ta = new ThinkingdataAnalytics(new BatchConsumer(serverURL, appid));
//If you want intranet transmission, you can initialize it as follows, false means uncompressed file, default gzip compression
//ThinkingdataAnalytics ta = new ThinkingdataAnalytics(new BatchConsumer(serverURL, appid,false));
//If you want to report in batches, you can initialize it as follows, now the default is 20 reports once.
//ThinkingdataAnalytics ta = new ThinkingdataAnalytics(new BatchConsumer(serverURL, appid, 100));
The serverURL
is the URL to transfer data, and the appid
is the APP ID of your project
If you are using Cloud as a Service, enter the following URL:
http://receiver.ta.thinkingdata.cn
If you are using the version of private deployment, enter the following URL:
http://Data Acquisition Address
Note: Enter the following URL before version 1.2.0:
http://receiver.ta.thinkingdata.cn/logagent
http://Data Acquisition Address/logagent
**(3) DebugConsumer: **Transmit data to the TA server one by one in real time, without matching the transmission tool. If the data is wrong, the entire data will not be put into storage, and a detailed error description will be returned. It is not recommended to use in the production environment.
ThinkingdataAnalytics ta = new ThinkingdataAnalytics(new DebugConsumer(serverUrl,appId));
//If you do not want to upload to the TA library, initialize it as follows:
//ThinkingdataAnalytics ta = new ThinkingdataAnalytics(new DebugConsumer(serverUrl,appId,true));
The serverURL
is the URL to transfer data, and the appid
is the APP ID of your project.
If you are using Cloud as a Service, enter the following URL:
http://receiver.ta.thinkingdata.cn
If you are using the version of private deployment, enter the following URL:
http://Data Acquisition Address
# II. Report Data
After the SDK initialization is completed, you can call track
to upload events. In general, you may need to upload more than a dozen to hundreds of different events. If you are using the TA background for the first time, we recommend You upload a few key events first.
If you have doubts about what kind of events you need to send, you can check the Quick Use Guide for more information.
# 2.1 Send Events
You can call track
to upload events. It is recommended that you set the attributes of the event and the conditions for sending information according to the previously combed doc. Here, take user payment as an example:
//Setting Visitor ID in Unlogged State
string distinctId= "distinctId";
//Set account ID after login
string accountId = "accountId";
Dictionary<string, object> properties= new Dictionary<string, object>();
// Set the user's IP address, the TA system will interpret the user's geographic location information based on the IP address, and if not, it will not report by default.
properties.Add("#ip", "123.123.123.123");
// Set the time when the event occurred, if not, the default is the current time
properties.Add("#time", DateTime.Now);
//Set Event Properties
properties.Add("Product_Name", "Product A");
properties.Add("Price", 30);
properties.Add("OrderId", "Order Number abc_123");
List<string> list1 = new List<string>();
list1.Add("str1");
list1.Add("str2");
list1.Add("str3");
properties.Add("array",list1);
// Upload event, including account ID and visitor ID
ta.Track(accountId, distinctId, "Payment", properties);
// You can also upload only the visitor ID
// ta.Track(null, distinctId, "Payment", properties);
// Or just upload account ID
// ta.Track(accountId, null, "Payment", properties);
**Note: **In order to ensure that the visitor ID and account ID can be bound smoothly, if you use the visitor ID and account ID in your game, we strongly recommend that you upload the two IDs at the same time, otherwise the account will not match, resulting in user Double calculation . The specific ID binding rules can refer to the user identification rules section.
- The name of the event can only start with a letter and can contain numbers, letters and an underscore "_". The maximum length is 50 characters and is not sensitive to letter case.
- Event attributes are of type
Dictionary < string, object >
, where each element represents an attribute; - The event attribute
Key
is the attribute name and is ofstring
type. It can only start with letters, including numbers, letters and underscore "_". The maximum length is 50 characters and is not sensitive to letter case. - Property values support five types: string, numeric,
bool
,DateTime
, andList
.
# 2.2 Set Public Event Properties
For some properties that need to appear in all events, you can call SetPublicProperties
to set the public event properties. We recommend that you set the public event properties before sending the event.
// Set Common Event Properties
Dictionary<string, object> superProperties= new Dictionary<string, object>();
superProperties.Add("server_version", "1.2.3A");
superProperties.Add("server_name", "A1001");
ta.SetPublicProperties(superProperties);
// Set Event Properties
Dictionary<string, object> properties= new Dictionary<string, object>();
properties.Add("Product_Name", "Product A");
properties.Add("Price", 30);
properties.Add("OrderId", "order number abc_123");
// Upload an event with the attributes of a common event and the event itself
ta.Track(accountId, distinctId, "Payment", properties);
/*
Equivalent to performing the following operations
Dictionary<string, object> properties= new Dictionary<string, object>();
properties.Add("server_version", "1.2.3A");
properties.Add("server_name", "A1001");
properties.Add("Product_Name", "Product A");
properties.Add("Price", 30);
properties.Add("OrderId", "order number abc_123");
ta.track(distinct_id,account_id,"Payment",properties)
*/
- The public event attribute is of type
Dictionary < string, object >
, where each element represents an attribute; - The public event attribute
Key
is the attribute name, which is ofstring
type. It can only start with letters, including numbers, letters and underscore "_", with a maximum length of 50 characters and is not sensitive to letter case; - Public event property values support five types: string, numeric,
bool
,DateTime
, andlist
.
If you call SetPublicPropperties
to set a previously set public event property, the previous property value is overwritten. If the public event property and the Key of a property in the track
upload event duplicate, the property of the event overrides the public event property:
// Sett Common Event Properties
Dictionary<string, object> superProperties= new Dictionary<string, object>();
superProperties.Add("server_version", "1.2.3A");
superProperties.Add("server_name", "A1001");
ta.SetPublicProperties(superProperties);
// Set the public event properties again, and the value of "server_name" becomes "B9999"
superProperties.clear();
superProperties.Add("server_name","B9999");
ta.SetPublicProperties(superProperties);
// Setting Event Properties
Dictionary<string, Object> properties= new Dictionary<string, object>();
properties.Add("server_version", "1.3.4");
properties.Add("Product_Name", "Product A");
properties.Add("Price", 30);
properties.Add("OrderId", "order number abc_123");
// Upload the event when the value of "server_version" is "1.3.4" and the value of "server_name" is "B9999"
ta.Track(accountId, distinctId, "Payment", properties);
If you want to empty all public event properties, you can call ClearPublicProperties
.
# III. User Attributes
TA platform currently supports the user feature setting interface for UserSet
, UserSetOnce
, UserAdd
, UserDelete
.
# 3.1 UserSet
For general user features, you can call UserSet
to set it. The attributes uploaded using this interface will overwrite the original attribute values. If the user feature does not exist before, the new user feature will be created. The type is the same as the type of the incoming attribute:
// Upload user property and the value "user_name" is "ABC"
Dictionary<string, object> properties= new Dictionary<string, object>();
properties.Add("user_name","ABC");
ta.UserSet(accountId,distinctId, properties);
properties.clear();
//Upload user properties again and the user's "user_name" is overwritten with "XYZ"
properties.Add("user_name","XYZ");
ta.UserSet(accountId,distinctId, properties);
The user feature
set by the UserSet is aDictionary < string, object >
type, where each element represents an attribute;- User feature
Key
is the attribute name, for thestring
type, the provisions can only start with a letter, including numbers, letters and underscore "_", the maximum length of 50 characters, not sensitive to letter case; - Property values support five types: string, numeric,
bool
,DateTime
, andlist
.
# 3.2 UserSetOnce
If the user feature you want to upload only needs to be set once, you can call UserSetOnce
to set it. When the attribute already has a value before, this information will be ignored:
// Upload user property and the value "user_name" is "ABC"
Dictionary<string, object> properties= new Dictionary<string, object>();
properties.Add("user_name","ABC");
ta.UserSetOnce(accountId,distinctId, properties);
properties.clear();
//Upload user property, the user's "user_name" has been set so the property settings are ignored
//The user_age for this user is not set, so the setting value is 18
properties.Add("user_name","XYZ");
properties.Add("user_age",18);
ta.UserSetOnce(accountId,distinctId, properties);
UserSetOnce
sets the same user feature types and restrictions as UserSet
.
# 3.3 UserAdd
When you want to upload a numeric attribute, you can call UserAdd
to accumulate the attribute. If the attribute has not been set, a value of 0 will be assigned before calculation. Negative values can be passed in, which is equivalent to subtraction operations.
//Upload user attributes and add 30 and 1 to the user's Total Revenue and VipLevel attributes, respectively
Dictionary<string, object> properties= new Dictionary<string, object>();
properties.Add("TotalRevenue",30);
properties.Add("VipLevel",1);
ta.UserAdd(accountId,distinctId, properties);
UserAdd
sets the same user feature type and restrictions as the UserSet
, but only for numeric user features.
# 3.4 UserDelete
If you want to delete a user, you can call UserDelete
to delete the user. You will no longer be able to query the user features of the user, but the events generated by the user can still be queried.
ta.UserDelete(accountId, distinctId);
# 3.5 UserUnSet
When you need to empty the value of a user's user feature, you can call UserUnset
to empty:
//Deleting an attribute of this user must be a collection of string types, such as:
List<string> list = new List<string>();
list.Add("nickname");
list.Add("age");
ta.UserUnSet(accountId, distinctId, list);
# 3.6 UserAppend
When you want to append the user feature value to the list type, you can call UserAppend
to append the specified attribute. If the attribute has not been created in the cluster, UserAppend
creates the attribute.
//User_ Append, additional set attributes
Dictionary<string, object> dictionary = new Dictionary<string, object>();
List<string> list = new List<string>(); //The data in the list ends up tostring
list.Add("true");
list.Add("test");
dictionary.Add("arrkey4",list);
ta.UserAppend(accountId,distinctId,dictionary);
# IV. Other Operations
# 4.1 Submit Data Immediately
ta.Flush();
Submit data to the appropriate receiver immediately.
# 4.2 Close sdk
ta.Close();
Close and exit sdk, please call this interface before shutting down the server to avoid data loss in the cache**.**
# V. Relevant Preset Attributes
# 5.1 Preset Properties for All Events
The following preset properties are the preset properties that all events in the C #SDK (including automatic collection events) will carry.
Attribute name | Chinese name | Description |
---|---|---|
#ip | IP address | The user's IP address needs to be manually set, and TA will use this to obtain the user's geographic location information |
#country | Country | The country where the user is located, generated according to the IP address |
#country_code | Country code | The country code of the country where the user is located (ISO 3166-1 alpha-2, that is, two uppercase English letters), generated based on the IP address |
#province | Province | The user's province is generated according to the IP address |
#city | City | The user's city is generated according to the IP address |
# lib | SDK type | The type of SDK you access, such as tga_csharp_sdk, etc |
#lib_version | SDK version | The version you access to the C #SDK |
# ChangeLog
# 1.3.1 2021-04-22
- Fix LoggerConsumer file lock creation failure when writing files
# 1.3.0 2020-12-29
- Added track_update interface to support updatable events
- Added track_overwrite interface to support rewritable events
- Added #first_check_id attribute to support the first occurrence of events
- Optimize LoggerConsumer and add the prefix of the specified build file
- Optimize LoggerConsumer to add automatic creation of non-existing directories
# v1.2.1 2020-03-16
- Fix data not flush in time
# v1.2.0 2020-02-13
- Data type support list type
- Added user_append interface to support attribute appending of user's array type
- Added user_unset interface to delete user features
- BatchConsumer performance optimization: support for configuring compression mode; remove Base64 encoding
- DebugConsumer Optimization: More complete and accurate validation of data at the server level
# v1.1.0 2019-09-24
- Add DebugConsumer for easy debugging interface
- Optimized LoggerConsumer, support log file segmentation by hour
- Remove the default size of a single LoggerConsumer file is 1G segmentation
- Optimize the code, fix the bug that the attribute is null times wrong, and improve stability
# v1.0.0 2019-07-09
- On-line LoggerConsumer, the basic functions of BatchConsumer