# Node.js SDK 利用ガイド
このガイドは、Node.jsSDKを使用してプロジェクトにデータをインポートする方法について説明します。GitHub (opens new window)でNode.js SDKのソースコードを入手することができます。
**最新バージョン：**1.2.2
**更新時間：**2021-10-14
# 1、SDKの統合
# 1.1 SDKのインストール
npmでNode.js SDKを取得します。
# SDK取得
npm install thinkingdata-node --save
# SDK更新
npm i thinkingdata-node@{バージョン番号}
# 1.2 SDKインスタンスの作成
コードファイルの冒頭にthinkingdata-nodeを導入：
var ThinkingAnalytics = require("thinkingdata-node");
SDKでデータをアップロードするには、まずSDKインスタンスを作成します。以下の3つのSDKインスタンスの初期化メソッドを提供します。
// Debug Mode: 1つずつ送信し，詳細なエラー情報を返す.
var ta = ThinkingAnalytics.initWithDebugMode("APP-ID", "https://SERVER_URL");
//データを格納せずデータの形式のみ検証したい場合，configでインポート:
//config = {
// dryRun: true
//};
//var ta = ThinkingAnalytics.initWithDebugMode('APP-ID', 'https://SERVER_URL',config);
// Batch Mode：一括で受信側に送信
var ta = ThinkingAnalytics.initWithBatchMode("APP-ID", "https://SERVER_URL");
//送信の初期化を設定：
//config = {
// batchSize: 2,//データflushを設定
// compress :false//デフォルトはtrue,gzip压缩を表し，falseは内部ネットワークで設定
//}
//var ta = ThinkingAnalytics.initWithBatchMode('APP-ID', 'https://SERVER_URL',config);
//
// Logging Mode: データをローカルログファイルに取り込み，LogBusと併用
var ta = ThinkingAnalytics.initWithLoggingMode("/PATH/TO/DATA");
3つのモードは次のとおりです。
(1) Debug Mode**：**データをリアルタイムでTAサーバーに転送し、データ形式が間違っている場合は詳細なエラー情報を返します。最初にDebugConsumerでデータ形式を検証することをお勧めします。受信プロジェクトAPP IDと受信側アドレスを初期化します。
(2)** Batch Mode：**一括リアルタイムでTAサーバにデータを転送するため、転送ツールを併用する必要はありません。ネットワーク状況が悪い場合にはデータが失われる可能性があるため、本番環境での使用は推奨しません。受信プロジェクトAPP IDと受信側アドレスを初期化します。
BatchModeは最初にデータをキャッシュに格納し、データ数が設定された値(batchSize、デフォルトは20)を超えるとアップロードを開始します。また、SDKの初期化時に設定することもできます。
// SDK初期化, 受信側アドレスを指定、APP ID、キャッシュサイズ
var ta = ThinkingAnalytics.initWithBatchMode("APP-ID", "https://SERVER_URL", {
batchSize: 10, // キャッシュデータ数が10になるとアップロードを開始
enableLog: true // 送信データの印刷を許可し, ログを開くと詳細な送信ログを印刷
});
**(3) Logging Mode：**データをリアルタイムでローカルファイルに書き込み、ファイルは日/時間で分割し、LogBusと併用してデータアップロードを行う必要があります。本番環境での使用をお勧めします。
Logging Modeはlog4jsを使用してデータをリアルタイムでローカルログファイルとして保存し、その後はLogBusでログファイルをTAデータベースにインポートします。
// ログデータファイル格納ディレクトリ
var logPath = "/home/app/logs/";
// SDKインスタンスの初期化
var ta = ThinkingAnalytics.initWithLoggingMode(logPath);
ログファイルはデフォルトで日単位で分割されます。SDKを初期化するときに設定オブジェクトを取り込むことでログ分割モードを時間単位に変更します。
// SDK初期化，時間単位でログファイルを分割.
var ta = ThinkingAnalytics.initWithLoggingMode(logPath, { rotateHourly: true });
TIP
pm2でNode.jsアプリケーションを管理するには、次の手順に従って起動パラメーターを設定する必要があります。
- pm2-intercomをインストール:
pm2 install pm2-intercom
- SDKの初期化時にpm2パラメーターを導入
// 初始化 SDK，按小时切分日志文件，指定 pm2 模式
var ta = ThinkingAnalytics.initWithLoggingMode(logPath, {
rotateHourly: true,
pm2: true
});
WARNING
pm2設定でinstance_varを指定した場合は、初期化設定でこのパラメーターを渡す必要があります。pm2設定でinstance_varを'INSTANCE_ID'に指定した場合、SDK初期化時に次のパラメーターを渡す必要があります。
// SDK初期化，時間単位でログファイルを分割し，pm2モードを指定し，pm2InstanceVarを指定
var ta = ThinkingAnalytics.initWithLoggingMode(logPath, {
rotateHourly: true,
pm2: true,
pm2InstanceVar: "INSTANCE_ID"
});
# 2、データアップロード
SDKの初期化が完了すると、taインターフェイスを使用してデータをアップロードします。
# 2.1 イベントの送信
trackを呼び出してイベントをアップロードすることができます。前の内容をもとに、イベントのプロパティと情報送信の条件を設定することをお勧めします。ここでは、イベントをアップロードする例を示します。
// イベントデータを定義
var event = {
// アカウントID （任意)
accountId: "node_test",
// ゲストID （任意)，アカウントID 和ゲストIDは空にしない
distinctId: "node_distinct_id",
// イベント名 （必須)
event: "test_event",
// イベント时间 (任意) を入力しない場合，インターフェースの呼び出し時間をイベント時間にする
time: new Date(),
// イベントIP (任意) IPアドレスを入れると，バックグラウンドで所在地の解析が可能
ip: "202.38.64.1",
// イベントプロパティ (任意)
properties: {
prop_date: new Date(),
prop_double: 134.1,
prop_string: "hello world",
prop_int: 67
},
// エラー時にコールバック (任意)
callback(e) {
if (e) {
console.log(e);
}
}
};
// イベントアップロード
ta.track(event);
パラメーターの説明:
- イベントの名前はアルファベットで始まり、数値、アルファベット、下線「_」を含むことができます。長さは最大50文字で大文字と小文字を区別しません。
- イベントのプロパティはMap型で、各要素は1つのプロパティを表します。
- イベントプロパティのKey値はプロパティの名前であり、string型でアルファベットで始まり、数値、アルファベット、下線「_」を含むことができます。長さは最大50文字で大文字と小文字を区別しません。
- イベントプロパティのValue値はプロパティ値であり、
string、数値型、bool、Date、配列型をサポートします。
SDKはローカルでデータ形式を検証します。ローカル検証をスキップしたい場合は、trackインターフェイスを呼び出すときにskipLocalCheckパラメーターを渡します。
// ローカルデータ検証をスキップ
ta.track(event, true);
# 2.2 パブリックイベントプロパティの設定
パブリックイベントプロパティは、すべてのイベントに含まれるプロパティです。通常のパブリックプロパティは固定値です。動的パブリックイベントプロパティも設定可能で、このプロパティはイベントアップロード時に値を取得し、イベントに渡します。同じプロパティがある場合、動的パブリックプロパティはパブリックプロパティを上書きします。
// パブリックプロパティを設定
ta.setDynamicSuperProperties(() => {
var date = new Date();
date.setYear(2018);
return {
super_date: date,
super_int: 5
};
});
// パブリックイベントプロパティを設定
ta.setSuperProperties({
super_int: 8, // 動的パブリックプロパティに上書きされるため,最終アップロードデータに表示しない.
super_debug_string: "hahahaha"
});
// パブリックイベントプロパティを削除
ta.clearSuperProperties();
# 3、ユーザープロパティの設定
# 3.1 userSet
通常のユーザープロパティは、userSetを呼び出して設定することができます。このインターフェイスを使用してアップロードしたプロパティは、元のプロパティ値を上書きします。過去にこのユーザープロパティが存在しなかった場合は、新しいユーザープロパティが作成されます。
// ユーザープロパティデータ
var userData = {
// アカウントID （任意)
accountId: "node_test",
// ゲストID （任意)，アカウントIDとゲストIDは空にしない
distinctId: "node_distinct_id",
// ユーザープロパティ
properties: {
prop_date: new Date(),
prop_double: 134.12,
prop_string: "hello",
prop_int: 666
},
// エラー時にコールバック (任意)
callback(e) {
if (e) {
console.log(e);
}
}
};
// ユーザープロパティ設定
ta.userSet(userData);
# 3.2 userSetOnce
アップロードするユーザープロパティが1回しか設定しない場合、userSetOnceを呼び出して設定することができます。このプロパティは既に値がある場合、この情報が無視されます。
ta.userSetOnce(userData);
# 3.3 userAdd
数値型プロパティをアップロードするには、userAddを呼び出して、そのプロパティに対して累積操作を行います。そのプロパティが設定されていない場合は、0を割り当ててから計算します。
// ユーザープロパティの累積
ta.userAdd({
accountId: "node_test",
properties: {
Amount: 222
}
});
# 3.4 userDel
あるユーザーを削除したい場合、userDel を呼び出してユーザーを削除することができます。それ以降、このユーザーのユーザープロパティを参照することができなくなるが、発生したイベントを参照することができます。
// ユーザーを削除
ta.userDel({
// アカウントID （任意)
accountId: "node_test",
// ゲストID （任意)，アカウントIDとゲストIDは空ではない
distinctId: "node_distinct_id"
});
# 3.5 userAppend
Array型にユーザープロパティ値を追加するには、user_appendを呼び出して、指定したプロパティに追加操作を行います。このプロパティはクラスターで作成されていない場合はuser_appendで作成することができます。
// ユーザーリストクラスにプロパティkey - array ,arrayをstring配列として追加
ta.userAppend({
accountId: "node_test",
properties: {
prop_array: ["str3", "str4"]
}
});
# 3.6 userUnset
ユーザーのユーザープロパティ値を削除したい場合、user_unsetを呼び出して指定したプロパティを空にすることができます。そのプロパティはクラスターで作成されていない場合、user_unsetがそのプロパティを作成しません。
//ユーザープロパティを削除
ta.userUnset({
accountId: "node_test",
property: "prop_double"
});
# 4、その他の操作
# 4.1 データの即時IO
この操作は特定のConsumer実装に関連しています。データを受信すると、Consumerはデータをキャッシュに保存し、特定の場合に実際のデータIO操作をトリガーして、全体的なパフォーマンスを向上させることができます。即時にデータを送信したい場合、Flushインターフェイスを呼び出します。
// 即時にデータを対応する受信側に送信
ta.flush();
# 4.2 SDKの終了
キャッシュ内のデータの消去を避けるため、プログラムを終了する前にこのインターフェイスを呼び出してください。
// SDKを終了
ta.close();
# 4.3 ログの起動
環境変数NODE_DEBUG=``=tdaを設定し、ログを開きます。
# ChangeLog
省略します。詳細は中国語版をご参照ください。