目录
此内容是否有帮助?

# 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 Frameworkapplication, 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 serverURLis the URL to transfer data, and the appidis 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 serverURLis the URL to transfer data, and the appidis 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 trackto 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 trackto 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 Keyis the attribute name and is of stringtype. 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, and List.

# 2.2 Set Public Event Properties

For some properties that need to appear in all events, you can call SetPublicPropertiesto 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 Keyis the attribute name, which is of stringtype. 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, and list.

If you call SetPublicProppertiesto 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 trackupload 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 UserSetto 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 featureset by the UserSet is a Dictionary < string, object >type, where each element represents an attribute;
  • User feature Keyis the attribute name, for the stringtype, 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, and list.

# 3.2 UserSetOnce

If the user feature you want to upload only needs to be set once, you can call UserSetOnceto 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);

UserSetOncesets the same user feature types and restrictions as UserSet.

# 3.3 UserAdd

When you want to upload a numeric attribute, you can call UserAddto 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);

UserAddsets 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 UserDeleteto 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 UserUnsetto 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 UserAppendto append the specified attribute. If the attribute has not been created in the cluster, UserAppendcreates 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

← Golang SDK User Guide →