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 アプリケーションを管理するには、次の手順に従って起動パラメーターを設定する必要があります。

1. pm2-intercom をインストール:

pm2 install pm2-intercom

2. 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

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