目录
此内容是否有帮助?

# Java SDK 利用ガイド

TIP

データをインポートする前に、インポート前の準備をご参照ください。

GitHub (opens new window)で Java SDK ソースを取得することができます。

**最新バージョン：**1.9.11.9.1

更新時間： 2021-12-20

# 1、SDK の統合と初期化

1.Maven で SDK を統合するには、pom.xmlファイルに次のコード(推奨)を追加してください。

<dependencies>
    // others...
    <dependency>
        <groupId>cn.thinkingdata</groupId>
        <artifactId>thinkingdatasdk</artifactId>
        <version>1.9.1</version>
    </dependency>
</dependencies>

2.jar パッケージを使用してプロジェクトをインポート

Java SDK JAR ダウンロード (opens new window)

3.SDK の初期化

//SDKの2つのメソッドを初期化，ConsumerはLoggerConsumer,BatchConsumer,DebugConsumerを含む
//デフォルト
ta = ThinkingDataAnalytics(Consumer);
//UUID重複除去の追加
bool enableUuid = true;
ta = ThinkingDataAnalytics(Consumer,enableUuid);

SDK インスタンスを取得するには、次の 3 つのメソッドがあります。

(1)LoggerConsumer**：**一括且つリアルタイムでローカルのテキストを書き、テキストは日で区切り、LogBus でアップロードします。

//LoggerConsumerを使用，デフォルトで日でファイルを区切る
ThinkingDataAnalytics ta = new ThinkingDataAnalytics(new ThinkingDataAnalytics.LoggerConsumer(LOG_DIRECTORY));

ファイルを時間単位で区切りたい場合は、次のようにコードを初期化します。

//LoggerConsumerの設定クラス
ThinkingDataAnalytics.LoggerConsumer.Config config =new  ThinkingDataAnalytics.LoggerConsumer.Config(LOG_DIRECTORY);
//時間単位で区切り，デフォルトでRotateMode.DAILYは日で区切る。
config.setRotateMode(ThinkingDataAnalytics.LoggerConsumer.RotateMode.HOURLY);
ThinkingDataAnalytics ta = new ThinkingDataAnalytics(new ThinkingDataAnalytics.LoggerConsumer(config));

サイズで区切りたい場合は、次のようにコードを初期化することできます。

//LoggerConsumer設定クラス
ThinkingDataAnalytics.LoggerConsumer.Config config =new  ThinkingDataAnalytics.LoggerConsumer.Config(LOG_DIRECTORY);
//日で区切りたい前提で，サイズで区切って，単位はM.例えば、2G分割ファイルを設定
config.setFileSize(2*1024);
//生成ファイルのプレフィックスを設定
config.setFilenamePrefix("prefix");
ThinkingDataAnalytics ta = new ThinkingDataAnalytics(new ThinkingDataAnalytics.LoggerConsumer(config));

LOG_DIRECTORYはローカルフォルダに書き込むアドレスで、LogBus の監視フォルダアドレスをここのアドレスに設定するだけで、LogBus を使用してデータの監視とアップロードができます。

**(2)BatchConsumer:**一括リアルタイムで TA サーバにデータを転送するため、転送ツールを併用する必要はありません。ネットワークの問題で送信に失敗した場合、3 回まで再試行し、再度失敗した場合、データをキャッシュに保存します。キャッシュのサイズは設定可能で、デフォルトで 50 のため、キャッシュ保存のデータ総量は最大 50*20(20 はアップロードの batch 値で、設定可能)です。長時間ネットワークが中断した場合、データが失われるリスクがあります。

//BatchConsumerの設定クラスを使用
ThinkingDataAnalytics ta = new ThinkingDataAnalytics(new ThinkingDataAnalytics.BatchConsumer(SERVER_URI, APP_ID));

データの圧縮方法を設定するには、次のようにコードを初期化します。

//BatchConsumer
ThinkingDataAnalytics.BatchConsumer.Config batchConfig = new ThinkingDataAnalytics.BatchConsumer.Config();
//設定可能な圧縮方法はgzip，lzo，lz4，noneで，デフォルトでgzip，内部ネットワークはnone使用可能
batchConfig.setCompress("gzip");
//設定可能な接続超過時間,単位はms
batchConfig.setTimeout(10000);//10s
ThinkingDataAnalytics ta = new ThinkingDataAnalytics(new ThinkingDataAnalytics.BatchConsumer(SERVER_URI, APP_ID,batchConfig));

データフラッシュバーの数を設定するには、次のようにコードを初期化します。

//BatchConsumer
ThinkingDataAnalytics.BatchConsumer.Config batchConfig = new ThinkingDataAnalytics.BatchConsumer.Config();
//デフォルトでTAシステムにflushするデータは20個で，以下の設定が可能
 batchConfig.setBatchSize(30);//flush数，デフォルトで20，デフォルト上限は7000.
ThinkingDataAnalytics ta = new ThinkingDataAnalytics(new ThinkingDataAnalytics.BatchConsumer(SERVER_URI, APP_ID,batchConfig));

SERVER_URIは転送データの uri で、APP_IDはプロジェクトの APP ID です。

クラウドサービスを使用している場合は、次の URL を入力してください。

http://ta-receiver.thinkingdata.io

オンプレミスサービスを使用している場合は、次の URL を入力してください。

http://数据采集地址

注意:バージョン 1.4.0 以前は次の URL を入力してください。

http://ta-receiver.thinkingdata.io/logagent
http://データ収集URL/logagent

(3)DebugConsumer**：リアルタイムで TA サーバーにデータを転送し、転送ツールを併用する必要はありません。データにエラーが発生した場合、データ全体が格納されず、詳細なエラー説明に戻ります。正式な環境での使用**を推奨しません。

ThinkingDataAnalytics ta = new ThinkingDataAnalytics(new ThinkingDataAnalytics.DebugConsumer(SERVER_URI, APP_ID));

データの格納ではなく、データ形式をチェックしたい場合は、次のようにコードを初期化することができます。

//デフォルトはtrue
ThinkingDataAnalytics ta = new ThinkingDataAnalytics(new ThinkingDataAnalytics.DebugConsumer(SERVER_URI, APP_ID,false));

SERVER_URIは転送データの uri で、APP_IDはプロジェクトの APP ID です。

クラウドサービスを使用している場合は、次の URL を入力してください。

http://ta-receiver.thinkingdata.io

オンプレミスサービスを使用している場合は、次の URL を入力してください。

http://数据采集地址

# 2、データの送信

SDK の初期化が完了した後、trackを呼び出してイベントをアップロードすることができます。通常、数十から数百の異なるイベントをアップロードする必要があります。TA を初めて使用する場合は、いくつかの重要なイベントをアップロードすることをお勧めします。

どのようなイベントを送信すれば良いかについて疑問がある場合、クイックガイドをご参照ください。

# 2.1 イベントの送信

trackを呼び出してイベントをアップロードすることができます。前の内容をもとに、イベントのプロパティと情報送信の条件を設定することをお勧めします。ここでは、ユーザーが商品を購入する例を示します。

//SDK初期化
ThinkingDataAnalytics ta = new ThinkingDataAnalytics(new ThinkingDataAnalytics.BatchConsumer(SERVER_URI, APP_ID));

//ゲストID"ABCDEFG123456789"設定
String distinct_id = "ABCDEFG123456789";

//ゲストID"TA_10001"設定
String account_id = "TA_10001";

//イベントプロパティ設定
Map<String,Object> properties = new HashMap<String,Object>();

// イベント発生時間設定，設定しない場合，デフォルトで現在時間を使用
properties.put("#time", new Date());

// ユーザーのipアドレスを設定，TAシステムはIPアドレスでユーザーの位置を解析し，設定しない場合，デフォルトでアップロードしいない
properties.put("#ip", "192.168.1.1");

properties.put("Product_Name", "商品A");
properties.put("Price", 30);
properties.put("OrderId", "订单号abc_123");

//
上传事件，包含用户的访客ID与账号ID，请注意不要将访客ID与账号ID写反
try {
            ta.track(account_id,distinct_id,"payment",properties);
            ta.flush();
        } catch (Exception e) {
		   //異常処理
            System.out.println("except:"+e);
     }

**注意：**ゲスト ID とアカウント ID をうまく紐づけるため、ゲームにゲスト ID とアカウント ID 両方を使用する場合は、この 2 つの ID を同時にアップロードすることをお勧めします。そうしないと、アカウントがマッチしない状況が発生し、計算を繰り返すことになります。具体的な ID 連携ルールはユーザー識別ルールをご参照ください。

  • イベントの名前はString型であり、アルファベットで始まり、数値、アルファベット、下線「_」を含むことができます。長さは最大 50 文字で大文字と小文字を区別しません。
  • イベントのプロパティはMap<String, Object>オブジェクトで、各要素は 1 つのプロパティを表します。
  • Key の値はプロパティの名前であり、String型で、アルファベットで始まり、数値、アルファベット、下線「_」を含むことができます。長さは最大 50 文字で大文字と小文字を区別しません。
  • Value はプロパティの値であり、String、Number、Boolean、Date、Listを含むことができます。

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

すべてのイベントに表示したいプロパティについては、setSuperPropertiesを使用してこれらのプロパティを パブリックイベントプロパティに設定することができます。 パブリックイベントプロパティはすべてtrackがアップロードされたイベントに追加されます。

Map<String, Object> superProperties = new HashMap<String,Object>();
//パブリックイベントプロパティの設定：サービス側名称
superProperties.put("server_name", "S10001");
//パブリックイベントプロパティの設定：サービス側バージョン
superProperties.put("server_version", "1.2.3");
//パブリックイベントプロパティの設定
ta.setSuperProperties(superProperties);

Map<String,Object> properties = new HashMap<String,Object>();
//パブリックイベントプロパティの設定
properties.put("Product_Name", "商品A");
properties.put("Price", 30);
//イベントアップロード，このイベントにパブリックイベントプロパティとイベントプロパティを含む
try {
            ta.track(account_id,distinct_id,"payment",properties);
        } catch (Exception e) {
		   //異常処理
            System.out.println("except:"+e);
     }

/** 全てのイベントにこれらのプロパティを追加
 *  properties.clear();
 *  properties.put("server_name", "S10001");
 *  properties.put("server_version", "1.2.3");
 *  properties.put("Product_Name", "商品A");
 *  properties.put("Price", 30);
 *try {
 *        ta.track(account_id,distinct_id,"payment",properties);
 *       } catch (Exception e) {
 *		   //異常処理
 *          System.out.println("except:"+e);
 *   }
 */
  • 共通イベントプロパティもMap<String, Object>オブジェクトで、各要素は 1 つのプロパティを表します。
  • Key の値はプロパティの名前であり、String型で、アルファベットで始まり、数値、アルファベット、下線「_」を含むことができます。長さは最大 50 文字で大文字と小文字を区別しません。
  • Value はプロパティの値であり、String、Number、Boolean、Date、Listを含むことができます。

setSuperPropertiesを呼び出して設定済みのパブリックイベントプロパティをアップロードすると、プロパティが上書きされます。パブリックイベントプロパティはtrackでアップロードされたプロパティの Key と重複している場合、そのイベントのプロパティがパブリックイベントプロパティを上書きします。

Map<String, Object> superProperties = new HashMap<String,Object>();
superProperties.put("server_name", "S10001");
superProperties.put("server_version", "1.2.3");
//パブリックイベントプロパティの設定
ta.setSuperProperties(superProperties);


superProperties.clear();
superProperties.put("server_name", "Q12345");
//パブリックイベントプロパティを再設定."server_name"が上書きされ，値は"Q12345"
ta.setSuperProperties(superProperties);

Map<String,Object> properties = new HashMap<String,Object>();
properties.put("Product_Name", "商品A");
//パブリックイベントプロパティと重複するプロパティを設定
superProperties.put("server_version", "1.2.4");
//イベントをアップロード，"server_version"のプロパティ値は"1.2.4"に上書きされ，"server_name"の値は"Q12345"

try {
           ta.track(account_id,distinct_id,"payment",properties);
      } catch (Exception e) {
		   //異常処理
           System.out.println("except:"+e);
     }

すべてのパブリックイベントプロパティを削除するには、clearSuperPropertiesを呼び出します。

# 3、ユーザープロパティ

TA プラットフォームで現在サポートしているユーザープロパティ設定インターフェイスは user_set、user_setOnce、user_add、user_del です。

# 3.1 user_set

通常のユーザープロパティは、user_setを呼び出して設定することができます。このインターフェイスを使用してアップロードしたプロパティは、元のプロパティ値を上書きします。過去にこのユーザープロパティが存在しなかった場合は、新しいユーザープロパティが作成され、アップロードしたプロパティ型と同様です。下記はユーザー名を設定する例を示します。

Map<String,Object> userSetProperties = new HashMap<String,Object>();
userSetProperties.put("user_name", "ABC");
userSetProperties.put("#time",new Date());

//ユーザープロパティをアップロード
try {
          ta.user_set(account_id,distinct_id,userSetProperties);
      } catch (Exception e) {
		   //異常処理
           System.out.println("except:"+e);
     }
userSetProperties.clear();
userSetProperties.put("user_name","abc");
userSetProperties.put("#time",new Date());

//ユーザープロパティを再アップロード，"user_name"の値は"abc"に上書きされる
try {
         ta.user_set(account_id,distinct_id,userSetProperties);
      } catch (Exception e) {
		   //異常処理
           System.out.println("except:"+e);
     }

user_set設定のユーザープロパティはMap<String, Object>オブジェクトで、各要素は 1 つのプロパティを表します。

Key の値はプロパティの名前であり、String型で、アルファベットで始まり、数値、アルファベット、下線「_」を含むことができます。長さは最大 50 文字で大文字と小文字を区別しません。

Value はプロパティの値であり、String、Number、Boolean、Date、Listを含むことができます。

# 3.2 user_setOnce

アップロードするユーザープロパティが 1 回しか設定しない場合、user_setOnceを呼び出して設定することができます。このプロパティは既に値がある場合、この情報が無視されます。下記はユーザー名を設定する例を示します。

Map<String,Object> userSetOnceProperties = new HashMap<String,Object>();
userSetOnceProperties.put("user_name", "ABC");
userSetOnceProperties.put("#time",new Date());

//ユーザープロパティをアップロード，"user_name"を"ABC"に新規作成
try {
        ta.user_setOnce(account_id,distinct_id,userSetOnceProperties);
      } catch (Exception e) {
		   //異常処理
           System.out.println("except:"+e);
     }

userSetOnceProperties.clear();
userSetOnceProperties.put("user_name","abc");
userSetOnceProperties.put("user_age",18);
userSetOnceProperties.put("#time",new Date());

//ユーザープロパティを再アップロード，"user_name"の値上書きされず"ABC"のまま；"user_age"の値は18
try {
        ta.user_setOnce(account_id,distinct_id,userSetOnceProperties);
      } catch (Exception e) {
		   //異常処理
           System.out.println("except:"+e);
     }

user_setOnceで設定したユーザープロパティ型と条件制限はuser_setと一致します。

# 3.3 user_add

数値型プロパティをアップロードするには、user_addを呼び出して、そのプロパティに対して累積操作を行います。そのプロパティが設定されていない場合は、0 を割り当ててから計算します。負の値も渡すことができ、減算に相当します。ここでは累積支払い額を例にします。

Map<String,Object> userAddProperties = new HashMap<String,Object>();
userAddProperties.put("total_revenue",30);
userAddProperties.put("#time",new Date());

//ユーザープロパティをアップロード，"total_revenue"の値は30
try {
        ta.user_add(account_id,distinct_id,userAddProperties);
      } catch (Exception e) {
		   //異常処理
           System.out.println("except:"+e);
     }

userAddProperties.clear();
userAddProperties.put("total_revenue",60);
userAddProperties.put("#time",new Date());

//ユーザープロパティを再アップロード，"total_revenue"の値は90
try {
        ta.user_add(account_id,distinct_id,userAddProperties);
      } catch (Exception e) {
		   //異常処理
           System.out.println("except:"+e);
     }

user_addで設定したユーザープロパティ型および条件制限はuser_setと一致するが、数値型のユーザープロパティのみが許可されます。

# 3.4 user_append

list 型にユーザープロパティ値を追加するには、user_appendを呼び出して、指定したプロパティに追加操作を行います。このプロパティはクラスターで作成されていない場合はuser_appendで作成することができます。

        List<String> appendList1 = new ArrayList<>();
        appendList1.add("12.2");
        appendList1.add("str");
        properties.put("arr1", appendList1);//配列型arr1にプロパティを追加
        List<String> appendList2 = new ArrayList<>();
        appendList2.add("2");
        appendList2.add("true");
		properties.put("arr2", appendList2);//配列型arr2にプロパティを追加
		try {
            tga.user_append(account_id, distinct_id, properties);
        } catch (Exception e) {
            //异常处理
            System.out.println("except:"+e);
        }

# 3.5 user_unset

ユーザーのユーザープロパティ値を削除したい場合、user_unsetを呼び出して指定したプロパティを空にすることができます。そのプロパティはクラスターで作成されていない場合、user_unsetがそのプロパティを作成しません。

// 単一ユーザープロパティの設定
try {
        ta.user_unset("key1");
      } catch (Exception e) {
		   //異常処理
           System.out.println("except:"+e);
     }

// 複数ユーザープロパティの設定
try {
      ta.user_unset("key1", "key2", "key3");
      } catch (Exception e) {
		   //異常処理
           System.out.println("except:"+e);
     }

// 複数ユーザープロパティを設定し，文字列を取り込む
String[] keys = {"key1", "key2"};
try {
        ta.user_unset(keys);
      } catch (Exception e) {
		   //異常処理
           System.out.println("except:"+e);
     }

# 3.6 user_del

あるユーザーを削除したい場合、user_deleteを呼び出してユーザーを削除することができます。それ以降、このユーザーのユーザープロパティを参照することができなくなるが、発生したイベントを参照することができます。この操作は取り返すしのつかない結果になる可能性があるので、ご注意ください。

try {
        ta.user_del(account_id,distinct_id);
      } catch (Exception e) {
		   //異常処理
           System.out.println("except:"+e);
     }

# 4、その他の操作

# 4.1 データの即時提出

ta.flush();

即時に対応する受信機にデータを送信します。

# 4.2 SDK の終了

try {
       ta.close();
      } catch (Exception e) {
		   //異常処理
           System.out.println("except:"+e);
     }

sdk を終了するには、キャッシュ内のデータの消去を避けため、サーバーをシャットダウンする前にこのインターフェイスを呼び出してください。

# 5、関連のプリセットプロパティ

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

次のプリセットプロパティは、Java SDK のすべてのイベント(自動収集イベントを含む)に含まれるプリセットプロパティです。

プロパティ名
 日本語
 説明
#ip
 IPアドレス
 ユーザーのIPアドレス。TAはユーザーの位置情報を取得。
#country
 国
 ユーザーの国。IPアドレスに基づいて生成。
#
country_code
 国コード
 ユーザーがいる国の国コード(ISO 3166-1 alpha-2、2大文字のアルファベット)。IPアドレスに基づいて生成。
#province
 省
 ユーザーがいる省。IPアドレスに基づいて生成。
#city
 都市
 ユーザーがいる都市。IPアドレスに基づいて生成。
#lib
 SDKタイプ
 SDKのタイプ。
Java
など。
#lib_version
 SDKバージョン
 Java SDKのバージョン。

# 6、高度な機能

v1.6.0 以降、SDK は更新可能なイベント、書き換え可能なイベントとの 2 つの特殊イベントのアップロードをサポートしています。この 2 つのイベントは、TA システム 2.8 以降のバージョンと併用する必要があります。特殊イベントは特定の場面でしか適用されないので、TA のクライアントとアナリストのもとに、特殊イベントのアップロードを行うようにしましょう。

# 6.1 更新可能なイベント

更新可能なイベントを通して、特定の場面でのイベントデータの変更要件を満たすことができます。更新可能なイベントは、イベントを識別する ID を指定し、更新可能なイベントオブジェクトの作成時に読み込むする必要があります。TA プラットフォームは、イベント名とイベント ID に基づいて更新するデータを決定します。

// 例： 更新可能なイベントをアップロード，イベント名は UPDATABLE_EVENTに仮定
Map<String, Object> properties = new HashMap<>();
properties.put("price",100);
properties.put("status",3);
// イベントプロパティアップロード後に status は 3, price は 100
ta.track_update(account_id, distinct_id,"UPDATABLE_EVENT","test_event_id",properties);

// イベントプロパティアップロード後に status は 5に更新され, price は変わらない不变
Map<String, Object> protertiesNew = new HashMap<>();
protertiesNew.put("status",5);
ta.track_update(account_id, distinct_id, "UPDATABLE_EVENT", "test_event_id", protertiesNew);

# 6.2 書き換え可能なイベント

書き換え可能なイベントは更新可能なイベントと似ており、違いとしては書き換え可能なイベントは最新のデータで過去データを完全に上書きするので、過去データを削除し、最新のデータを格納することに相当します。TA プラットフォームは、イベント名とイベント ID に基づいて更新するデータを決定します。

// 例： 書き換え可能なイベントをアップロードし，イベント名は OVERWRITE_EVENTに仮定
Map<String, Object> properties = new HashMap<>();
properties.put("price",100);
properties.put("status",3);
// イベントプロパティアップロード後に status は 3, price は 100
ta.track_overwrite(account_id, distinct_id, "OVERWRITE_EVENT","test_event_id", properties);

Map<String, Object> protertiesNew = new HashMap<>();
protertiesNew.put("status",5);

// イベントプロパティアップロード後に status は 5に更新され, price は削除される
ta.track_overwrite(account_id, distinct_id, "OVERWRITE_EVENT", "test_event_id", protertiesNew);

# 6.3 初期イベントチェック機能

初期イベントチェック機能を使用するには、properties に#first_check_id フィールドを設定する必要があります。タイプは文字列で、このフィールドは初期イベントをチェックする識別 ID で、この ID で最初に現れたデータは格納されるが、その後に現れたデータは格納されません。異なるイベントの#first_check_id は互いに独立しているので、各イベントの初回チェックは互いに干渉しません。

// 例： 書き換え可能なイベントをアップロードし，イベント名は OVERWRITE_EVENTに仮定
Map<String, Object> properties = new HashMap<>();
properties.put("price",100);
properties.put("status",3);
properties.put("#first_check_id","123456");
// イベントプロパティをアップロード
ta.track(account_id, distinct_id, "EVENT","test_event_id", properties);

# 6.4 定時リフレッシュ機能

デフォルトで、JAVA SDK は現在のデータサイズに基づいて自動的に flush()が実行され、デフォルトで 8K を超えると flush()が呼び出されます。v1.7.0 には定時リフレッシュ機能が追加され、BatchConsumer と LoggerConsumer は Config の interval と autoFlush パラメーターを設定して定時リフレッシュ機能をオンにすることができます。

ThinkingDataAnalytics.BatchConsumer.Config config = new ThinkingDataAnalytics.BatchConsumer.Config();
config.setAutoFlush(true);
//intervalは定時時間で，单位は秒で，デフォルト値は3.
config.setInterval(5);
ThinkingDataAnalytics tga = new ThinkingDataAnalytics(new ThinkingDataAnalytics.BatchConsumer("http://localhost:8991", "APP_ID", config));

# ChangeLog

省略します。詳細は中国語版をご参照ください。