目录
此内容是否有帮助?

# C SDK User Guide

TIP

Before accessing, please read the preparation before accessing .

You can get the C SDK source code in GitHub (opens new window).

**The latest version is **: 1.2.2

**Updated **: 2021-07-01

C SDK download address (opens new window)

# I. Integrate and Initialize SDK

# 1.1 Integrated SDK

Download the C SDK (opens new window)and unzip it to introduce the following files into the project

./c-sdk_version/include/thinkingdata.h
./c-sdk_version/lib/libthinkingdata.a

# 1.2 Initialize SDK

You can get an SDK instance by:

    //Generate config
    TAConfig* config = ta_init_properties();

    //Configuration Log Path YOUR_ LOG_ PATH needs to be changed to a directory for log storage
    TA_ASSERT(TA_OK == ta_add_string("file_path", "YOUR_LOG_PATH", strlen("YOUR_LOG_PATH"), config));
    //Configure log prefix
    TA_ASSERT(TA_OK == ta_add_string("file_prefix", "test", strlen("test"), config));

    //Time Sharing Default Hour Sharing
    //TA_ASSERT(TA_OK == ta_add_int("rotate_mode", DAILY, config)); //Divide by day
    TA_ASSERT(TA_OK == ta_add_int("rotate_mode", HOURLY, config)); //Split by hour

    //Divided by file size in MB
    //TA_ASSERT(TA_OK == ta_add_int("file_size", 1024, config));

    //Generate SDK instance
    TALoggingConsumer* consumer = NULL;
    if (TA_OK != ta_init_logging_consumer(&consumer, config)) {
        fprintf(stderr, "Failed to initialize the consumer.");
        return 1;
    }
    ta_free_properties(config);

    ThinkingdataAnalytics *ta = NULL;
    if (TA_OK != ta_init(consumer, &ta)) {
        fprintf(stderr, "Failed to initialize the SDK.");
        return 1;
    }

TALoggingConsumerwill generate log files in batches in real time. The files are divided by hours by default and need to be uploaded with LogBus.

YOUR_LOG_PATHIf you need to change to the directory where the log is stored, you can use LogBus to monitor the upload of data by simply setting the listening folder address of LogBus to the address here.

# II. Reporting of 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:

    const char* distinct_id = "ABC123";
    const char* account_id = "TA_10001";

    //Report event data without custom attributes, note account_ ID and distinct_ ID must be set to at least one of them
    TA_ASSERT(TA_OK == ta_track(NULL, distinct_id, "test", NULL, ta));

    // Generate custom properties
    TAProperties* properties = ta_init_properties();

    // Set the time when the event occurred, if not set, the default is the current time, ** Note that the type of ** #time must be time_ t
    TA_ASSERT(TA_OK == ta_add_date("#time", time(NULL), 0, properties));

    // Set the user's IP address, the TA system will interpret the user's geographic location information based on the IP address, if not, it will default to not report
    TA_ASSERT(TA_OK == ta_add_string("#ip", "192.168.1.1", strlen("192.168.1.1"), properties));

    // Add Custom Properties
    TA_ASSERT(TA_OK == ta_add_string("product_name", "Product", strlen("Product"), properties));
    TA_ASSERT(TA_OK == ta_add_number("price", 30.989, properties));
    TA_ASSERT(TA_OK == ta_add_int("coin", -30, properties));
    TA_ASSERT(TA_OK == ta_add_string("order_id", "abc_123", strlen("abc_123"), properties));
    TA_ASSERT(TA_OK == ta_add_date("login_time", time(NULL), 0, properties));
    TA_ASSERT(TA_OK == ta_add_bool("is_firstBuy", true, properties));
    TA_ASSERT(TA_OK == ta_add_bool("is_test", false, properties));

    // From v1. Starting with Version 1.0, you can call `ta_ Append_ Array` adds an attribute of type array.
    TA_ASSERT(TA_OK == ta_append_array("product_buy", "product_name1", strlen("product_name1"), properties));
    TA_ASSERT(TA_OK == ta_append_array("product_buy", "product_name2", strlen("product_name2"), properties));

    //Report event data with custom attributes, also account_ ID and distinct_ ID must be set to at least one of them
    TA_ASSERT(TA_OK == ta_track(account_id, distinct_id, "test", properties, ta));
    ta_free_properties(properties);
  • The name of the event is of type stringand can only begin with a letter. It can contain numbers, letters and an underscore "_". The length is up to 50 characters and is not sensitive to letter case.
  • The attribute type of the event is TAProperties, which can be added by ta_add_stringadding string attribute, ta_add_numberadding numeric attribute, ta_add_intadding intattribute, ta_add_booladding boolvalue, ta_add_dateadding datetype value, ta_append_arrayadding array type.
  • The value of Key is the name of the attribute, which is of string type. It is stipulated that it can only start with letters, contain numbers, letters and underscore "_", and is up to 50 characters in length. It is not sensitive to case of letters.
  • Value is the value of the property, which can be int, number, string, bool, dateand array types.

# 2.2 Set Public Event Properties

For some properties that need to appear in all events, you can call the ta_set_super_propertiesto set the public event properties. We recommend that you set the public event properties before sending the event.

You can also clear a public property that has been set by ta_unset_super_propertiesYou can also clear all public properties that have been set by ta_clear_super_properties.

    //Common Attribute Operations
    TAProperties* super_properties = ta_init_properties();

    //Add Common Attributessuper_property_key和super_property_key2
    TA_ASSERT(TA_OK == ta_add_string("super_property_key", "super_property_value", strlen("super_property_value"), super_properties));
    TA_ASSERT(TA_OK == ta_add_string("super_property_key2", "super_property_value2", strlen("super_property_value"), super_properties));

    //Set Common Properties
    ta_set_super_properties(super_properties, ta);

    //Report data, at which point events will have common attributes
    TA_ASSERT(TA_OK == ta_track(account_id, distinct_id, "test_super", NULL, ta));

    //Clear Common Attribute super_ property_ key2
    ta_unset_super_properties("super_property_key2", ta);

    //Report data, common attribute super_ Property_ Key2 is cleared and only the common attribute super_is present in the event property_ value
    TA_ASSERT(TA_OK == ta_track(account_id, distinct_id, "test_super2", NULL, ta));

    //Clear all public attributes
    ta_clear_super_properties(ta);

    //Report data, all public attributes are cleared, and events do not have any public attributes
    TA_ASSERT(TA_OK == ta_track(account_id, distinct_id, "test_super3", NULL, ta));
    ta_free_properties(super_properties);

# 2.3 Set Dynamic Public Event Properties

In v1.1.0, the feature of dynamic public attributes is added, that is, public attributes can obtain the current value when reporting, so that variable public attributes such as membership level can be easily reported. After setting the dynamic public property class, the SDK will automatically get the properties in the dynamic_properties_funcwhen the event is reported and add them to the triggered event. The following example is to add time to the event every time the report is reported. When the event is triggered, the return value of the dynamic_properties_funcwill be added to the event property.

TAProperties *dynamic_properties_func() {
    TAProperties *properties = ta_init_properties();
    TA_ASSERT(TA_OK == ta_add_date("dynamic", time(NULL), 0, properties));
    return properties;
}
 // Setting Dynamic Common Properties
ta_set_dynamic_properties(&dynamic_properties_func, ta);

# III. User Attributes

TA platform currently supports the user feature setting interface is ta_user_set, ta_user_setOnce, ta_user_add, ta_user_del, ta_user_append.

# 3.1 ta _ user _ set

For general user feature, you can call ta_user_setto 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"
    TAProperties* user_properties = ta_init_properties();
    TA_ASSERT(TA_OK == ta_add_string("user_name", "ABC", strlen("ABC"), user_properties));
    TA_ASSERT(TA_OK == ta_user_set(account_id, distinct_id, user_properties,ta));
    ta_free_properties(user_properties);

    //Upload user properties, the user's "user_name" is set to "XYZ"
    TAProperties* user_properties2 = ta_init_properties();
    TA_ASSERT(TA_OK == ta_add_string("user_name", "XYZ", strlen("XYZ"), user_properties2));
    TA_ASSERT(TA_OK == ta_user_set(account_id, distinct_id, user_properties2,ta));
    ta_free_properties(user_properties2);
  • ta_user_setThe attribute type of the user feature set is TAProperties, which can be ta_add_stringadded by adding string attribute, ta_add_numberadding numeric attribute, ta_add_intadding intattribute, ta_add_booladding boolvalue, ta_add_dateadding datetype value, ta_append_arrayadding array type.
  • The value of Key is the name of the attribute, which is of stringtype. It is stipulated that it can only start with letters, contain numbers, letters and underscore "_", and is up to 50 characters in length. It is not sensitive to case of letters.
  • Value is the value of the property, which can be int, number, string, bool, dateand array types.

# 3.2 ta_user_setOnce

If the user feature you want to upload only needs to be set once, you can call ta_user_setOnceto 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"
    TAProperties* user_properties = ta_init_properties();
    TA_ASSERT(TA_OK == ta_add_string("user_name", "ABC", strlen("ABC"), user_properties));
    TA_ASSERT(TA_OK == ta_user_setOnce(account_id, distinct_id, user_properties,ta));
    ta_free_properties(user_properties);

    //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
    TAProperties* user_properties2 = ta_init_properties();
    TA_ASSERT(TA_OK == ta_add_string("user_name", "XYZ", strlen("XYZ"), user_properties2));
    TA_ASSERT(TA_OK == ta_add_int("Age", 18, user_properties2));
    TA_ASSERT(TA_OK == ta_user_setOnce(account_id, distinct_id, user_properties2,ta));
    ta_free_properties(user_properties2);

ta_user_setOnceThe user feature type and restrictions set are consistent with ta_user_set.

# 3.3 ta_user_add

When you want to upload a numeric attribute, you can call ta_user_addto 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.

    //Set User Properties
    TAProperties* user_properties = ta_init_properties();
    TA_ASSERT(TA_OK == ta_add_int("Level", 3, user_properties));

    //Upload user attributes and add 3 to the user's Level attributes
    TA_ASSERT(TA_OK == ta_user_add(account_id, distinct_id, user_properties, ta));
    ta_free_properties(user_properties);

ta_user_addInterface property values are only allowed to pass in types int and number.

# 3.4 ta _ user _ del

If you want to delete a user, you can call ta_user_delto 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_ASSERT(TA_OK == ta_user_del(account_id, distinct_id, ta));

# 3.5 ta_user_append

Starting with v1.1.0, you can call ta_user_appendto append to user features of type array.

TAProperties *array_properties = ta_init_properties();
TA_ASSERT(TA_OK == ta_append_array("product_buy", "product_name3", strlen("product_name3"), array_properties));
TA_ASSERT(TA_OK == ta_append_array("product_buy", "product_name4", strlen("product_name4"), array_properties));
TA_ASSERT(TA_OK == ta_user_append(account_id, distinct_id, array_properties, ta));
ta_free_properties(array_properties);

# IV. Other Operations

# 4.1 Submit Data Immediately

    ta_flush(ta);

Submit data to the appropriate receiver immediately.

# 4.2 Close sdk

    ta_free(ta);
    ta_consumer_free(consumer);

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 included with all events in the C SDK, including AutoCollect events.

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 city where the user is located, generated according to the IP address
# lib
 SDK type
 The type of SDK you access, such as tga_c_sdk, etc
#lib_version
 SDK version
 The version you access to the C SDK

# ChangeLog

# 1.2.2 2021-07-01

  • Adapt to windows environment

# 1.2.1 2021-06-09

  • No longer use stdbool library

# 1.2.0 2020-12-07

  • Support specifying log prefix
  • Add automatic directory creation

# 1.1.0 2020-02-12

  • Support array data
  • Add user_append interface
  • Support dynamic public property settings
  • Support setting "#uuid" for background use

# 1.0.0 2019-09-29

  • debug consumer
  • logger consumer
  • support track/user_set/user_setOnce/user_add/user_del
  • support super properties

← C #SDK User Guide →