C SDK 利用ガイド

TIP

アクセスする前に、アクセス前アクセス前準備。

GitHub でGitHub (opens new window)C SDK ソースを取得できます。

最新バージョンはは: 1.2.2

更新時間は: 2021-07-01

C SDK ダウンロードアドレス (opens new window)

まず、SDK の統合と初期化

1.1 統合 SDK

ダウンロードC SDK (opens new window)して解凍すると、プロジェクトに

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

1.2 SDK の初期化

次の方法で SDK インスタンスを取得できます。

    //生成config
    TAConfig* config = ta_init_properties();

    //配置日志路径 YOUR_LOG_PATH 需要更改为日志存储的目录
    TA_ASSERT(TA_OK == ta_add_string("file_path", "YOUR_LOG_PATH", strlen("YOUR_LOG_PATH"), config));
    //配置日志前缀
    TA_ASSERT(TA_OK == ta_add_string("file_prefix", "test", strlen("test"), config));

    //按时间切分 默认按小时切分
    //TA_ASSERT(TA_OK == ta_add_int("rotate_mode", DAILY, config)); //按天切分
    TA_ASSERT(TA_OK == ta_add_int("rotate_mode", HOURLY, config)); //按小时切分

    //按文件大小切分，单位是MB
    //TA_ASSERT(TA_OK == ta_add_int("file_size", 1024, config));

    //生成SDK实例
    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;
    }

TALoggingConsumerはリアルタイムでログブックを生成します。テキストはデフォルトで時間単位です。

YOUR_LOG_PATHログストアのディレクトリに変更する必要があります。LogBus のリスニングフォルダアドレスをここに設定するだけで、LogBus を使用してデータをリスニングアップロードできます。

二、データを報告する

SDK の初期化が完了すると、trackを呼び出してイベントをアップロードできます。通常、ダースから数百の異なるイベントをアップロードする必要がある場合があります。

どのようなイベントを送信する必要があるか疑問がある場合は、クイッククイック使用ガイド参照してください。

2.1 送信イベント

を呼び出してtrackイベントをアップロードすることができます。イベントの属性と情報を送信する条件を設定することをお勧めします。

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

    //上报不带自定义属性的事件数据，注意account_id 和 distinct_id 必须至少设置其中一个
    TA_ASSERT(TA_OK == ta_track(NULL, distinct_id, "test", NULL, ta));

    // 生成自定义属性
    TAProperties* properties = ta_init_properties();

    // 设置事件发生的时间，如果不设置的话，则默认使用为当前时间，**注意** #time的类型必须是time_t
    TA_ASSERT(TA_OK == ta_add_date("#time", time(NULL), 0, properties));

    // 设置用户的ip地址，TA系统会根据IP地址解析用户的地理位置信息，如果不设置的话，则默认不上报
    TA_ASSERT(TA_OK == ta_add_string("#ip", "192.168.1.1", strlen("192.168.1.1"), properties));

    // 添加自定义属性
    TA_ASSERT(TA_OK == ta_add_string("product_name", "商品", strlen("商品"), 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));

    // 从 v1.1.0版本 开始，您可以调用 `ta_append_array` 对 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));

    //上报带有自定义属性的事件数据，同样account_id 和 distinct_id 必须至少设置其中一个
    TA_ASSERT(TA_OK == ta_track(account_id, distinct_id, "test", properties, ta));
    ta_free_properties(properties);

• イベントの名前はstring型で、文字で始まるだけで、数字、文字、下線「_」を含めることができ、長さは最大 50 文字で、文字の大文字と小文字には敏感ではない。
• イベントのプロパティタイプはTAPropertiesで、ta_add_string文字列型プロパティ、で数値型``型プロパティ、追加``bool``値、
• Key の値はプロパティの名前であり、文字列型であり、数字、文字、下線「_」を含む文字でのみ開始できることを規定し、最大 50 文字の長さであり、文字の大文字と小文字には敏感ではありません。
• Value はプロパティの値で、int、number、string、bool、date、配列型

2.2 パブリックイベントプロパティの設定

すべてのイベントに表示する必要があるプロパティプロパティの場合、ta_set_super_propertiesを呼び出して共通イベントプロパティを設定できます。イベントを送信する前に、共通イベントプロパティを設定することをお勧めします。

また、を使用クリアするか、ta_clear_super_properties を使用して設定すべての共通プロパティをクリアできます。

    //公共属性操作
    TAProperties* super_properties = ta_init_properties();

    //添加公共属性super_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));

    //设置公共属性
    ta_set_super_properties(super_properties, ta);

    //上报数据，此时事件中将会带有公共属性
    TA_ASSERT(TA_OK == ta_track(account_id, distinct_id, "test_super", NULL, ta));

    //清除公共属性super_property_key2
    ta_unset_super_properties("super_property_key2", ta);

    //上报数据，公共属性super_property_key2被清除，此时事件中只会带有公共属性super_property_value
    TA_ASSERT(TA_OK == ta_track(account_id, distinct_id, "test_super2", NULL, ta));

    //清空所有公共属性
    ta_clear_super_properties(ta);

    //上报数据，所有公共属性被清除，此时事件中不带有任何公共属性
    TA_ASSERT(TA_OK == ta_track(account_id, distinct_id, "test_super3", NULL, ta));
    ta_free_properties(super_properties);

2.3 動的パブリックイベントプロパティの設定

v1.1.0 では、動的共通属性の特性が新たに追加され、共通属性は報告時に当時の値を取得できるようになり、会員等級などの可変共通属性が便利に報告できるようになった。をta_set_dynamic_properties使用して動的パブリックプロパティクラスを設定すると、SDK はイベントの通知時に自動的にdynamic_properties_funcのプロパティを取得し、トリガーされたイベントに追加します。次の例では、タイムアップのたびにイベントに時間を追加し、イベントがトリガーされるとdynamic_properties_funcの戻り値をイベントプロパティに追加します。

TAProperties *dynamic_properties_func() {
    TAProperties *properties = ta_init_properties();
    TA_ASSERT(TA_OK == ta_add_date("dynamic", time(NULL), 0, properties));
    return properties;
}
 // 设置动态公共属性
ta_set_dynamic_properties(&dynamic_properties_func, ta);

三、ユーザー属性

TA プラットフォームで現在サポートされているユーザープロパティ設定インターフェイスはta_user_set、、、ta_user_add、です、です。

3.1 ta_user_set

一般的なユーザープロパティの場合、ta_user_setを呼び出して設定できます。インターフェイスを使用してアップロードされたプロパティは元のプロパティ値を上書きします。ユーザープロパティが存在しない場合は、新しいユーザープロパティが作成されます。

    // 上传用户属性，"user_name"的值为"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);

    //上传用户属性，该用户的"user_name"被设置成"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_set設定するユーザープロパティのプロパティタイプはTAPropertiesで、ta_add_string文字列型プロパティ、ta_add_numberで数値型プロパティ、ta_add_int
• Key の値はプロパティの名前で、string型で、数字、文字、下線「_」を含む文字で始まることができ、最大 50 文字で、文字の大文字と小文字には敏感ではない。
• Value はプロパティの値で、int、number、string、bool、date、配列型

3.2 ta_user_set Once

アップロードするユーザープロパティが一度設定されている場合は、ta_user_setOnceを呼び出して設定できます。

    // 上传用户属性，"user_name"的值为"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);

    //上传用户属性，该用户的"user_name"已设置因此忽略该属性设置
    //该用户的"user_age"没有被设置，因此设置值为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_setOnce設定のユーザー属性タイプと制限条件はと一致する。

3.3 taユーザー追加

数値型のプロパティをアップロードする場合は、ta_user_addを呼び出してアキュムレータ操作を実行できます。プロパティが設定されていない場合は、0 を割り当ててから計算します。負の値を渡すことができます。減算操作と同じです。

    //设置用户属性
    TAProperties* user_properties = ta_init_properties();
    TA_ASSERT(TA_OK == ta_add_int("Level", 3, user_properties));

    //上传用户属性，给该用户的"Level"属性加上3
    TA_ASSERT(TA_OK == ta_user_add(account_id, distinct_id, user_properties, ta));
    ta_free_properties(user_properties);

ta_user_addインターフェイスプロパティ値は、受信した int、number タイプのみを許可します。

3.4 ta_user_del

ユーザーを削除する場合は、ta_user_delを呼び出して削除できます

    TA_ASSERT(TA_OK == ta_user_del(account_id, distinct_id, ta));

3.5 ta_user_append

バージョン 1.1.0 から、ta_user_append を呼び出して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);

四、その他の操作

4.1 即時データ提出

    ta_flush(ta);

すぐに対応する受信機にデータを送信

4.2 SDK のシャットダウン

    ta_free(ta);
    ta_consumer_free(consumer);

sdk を閉じて終了し、サーバーを閉じる前にこのインターフェイスを呼び出して、キャッシュ内のデータが失わ

V.関連するプリセットプロパティ

5.1 すべてのイベントのプリセットプロパティ

次のプリセットプロパティは、自動取得イベントを含む C SDK 内のすべてのイベントに含まれるプリセットプロパティ

プロパティ名	日本語の	説明
#ip	IPアドレス	ユーザーのIPアドレスは、手動で設定する必要があり、TAはユーザーの地理的位置情報
#国	国	ユーザーの国は、IPアドレスに基づいて生成されます
#カントリーコード	国コード	ユーザーがいる国の国コード(ISO 3166-1 alpha-2、つまり2大文字英字)は、IPアドレスに基づいて生成
#県	州	ユーザーの州、IPアドレスに基づいて生成
#都市	都市	ユーザーの都市は、IPアドレスに基づいて生成されます
#lib	SDKタイプ	SDKにアクセスするタイプ(tga_c_sdkなど)
#リブバージョン	SDKバージョン	C SDKのバージョンにアクセスします

チェンジログ

1.2.2 2021-07-01

• Windows 環境に適応

1.2.1 2021-06-09

• stdbool ライブラリを使わない

1.2.0 2020-12-07

• ログプレフィックスの指定をサポート
• 自動ディレクトリ作成の追加

1.1.0 2020-02-12

• サポート array データ
• 新しい user_append インターフェイス
• 動的共通プロパティ設定
• 「#uuid」の設定に対応し、バックグラウンドでの使用

1.0.0 2019-09-29

• デバッグコンシューマー
• ロガーコンシューマー
• サポートトラック/ユーザーセット/ユーザーセット Once/ユーザーアド/ユーザーデル
• スーパープロパティをサポート