Node
最新バージョン:v0.0.2
更新日:2026-10-29
1. 概要
AE 6.1から、実験スイートでは管理画面で実験を作成し、対照群とテストグループに異なる変数値を構成できます。Node.jsサーバーサイド実験SDKは、これらのFeature構成を取得します。業務側が現在のユーザー識別情報とFeature Keyを渡すと、構成センター(RCC)がリモートトラフィック分割を行い、SDKが構成値と割り当てられた実験の情報を返します。業務で構成を適用した後、実際のインプレッションのタイミングでイベントを送信します。
- Feature Keyは管理画面で構成する変数の識別子です。例ではcheckout_buttonを使用しています。導入時には、プロジェクトで実際に公開したKeyに置き換えてください。
- createClient()はクライアントの検証と作成のみを行います。ネットワークにはアクセスせず、構成も自動取得しません。client.fetch(request)でクエリを実行してください。
- 実験に割り当てられなくても、管理画面のデフォルト構成値が返される場合があります。Featureに値があるかどうかと、実験に割り当てられたかどうかは別の判定です。
- 現在のバージョンはリモートトラフィック分割(REMOTE)のみに対応しています。LOCALは予約値であり、渡すとINVALID_CONFIGエラーになります。結果キャッシュと業務のデフォルト値はローカルトラフィック分割を行いません。
2. 導入
2.1 環境と依存関係
Node.js 12.0.0以上が必要です。SDKはCommonJS形式で公開されており、TypeScriptの型宣言を提供しています。以降のCommonJSの例は、対応する最小ランタイムで使用できます。
SDKはnpmで公開されています。最新バージョンをインストールしてください。
npm install td-feature-node@latest
npmは本番用の依存関係もインストールします。その中には公式データ収集SDKのthinkingdata-node@1.5.0が含まれます。業務での実行時にTypeScriptやその他の開発ツールは不要です。インストール時には、構成済みのnpm registryにアクセスできる必要があります。
2.2 導入前の準備
| 情報 | 用途 |
|---|---|
| appId | 実験プロジェクトのApp ID。プラットフォームが提供する値を使用してください。 |
| serverUrl | リモート判定とインプレッション収集に対応するサービスのベースURL。例:https://service.example.com。 |
| Feature Key | プラットフォームで構成・公開済みの変数識別子。 |
| 現在のユーザー識別情報 | accountId、distinctIdの少なくとも一方が空でない文字列であり、管理画面の振り分け主体とグループ条件を満たす必要があります。 |
| カスタムリクエストパラメータ | 管理画面のルールで必要なコンテキスト。パラメータ名、型、意味は管理画面の構成に一致させてください。 |
3. 初期化とクイックスタート
3.1 完全な例
quickstart.jsとして保存し、App ID、サービスURL、ユーザー識別情報、業務用Keyを実際の値に置き換えて、node quickstart.jsを実行してください。この例はデフォルト構成を使用し、すべてのKeyを取得してcheckout_buttonを読み取り、結果の適用後にインプレッションを手動送信します。SDKはデータ収集インスタンスを自動作成します。
const { createClient, SplitMode } = require('td-feature-node');
// 常駐サービスでは、プロセスごと、プロジェクトごとに1つのClientを再利用する。
const client = createClient({
appId: 'YOUR_APP_ID',
serverUrl: 'https://YOUR_SERVER_URL',
splitMode: SplitMode.REMOTE,
});
async function main() {
try {
const config = await client.fetch({
accountId: 'user_123',
distinctId: 'visitor_456',
// featureKeysを指定せず、現在の識別情報で取得可能なすべての構成を取得する。
});
console.log('今回返されたすべてのFeature Key:', Object.keys(config.features));
const feature = config.features['checkout_button'];
const buttonStyle = feature ? feature.asString('control') : 'control';
console.log('適用したボタンスタイル:', buttonStyle); // 業務で実際に使用するロジックに置き換える。
// 結果を実際に適用してからインプレッションを送信する。有効な実験に割り当てられていない場合、SDKはスキップする。
client.expose(feature, { scene: 'checkout' });
} catch (error) {
// リクエスト失敗時は業務のデフォルト値を使用し、実験結果の構築やインプレッション送信は行わない。
console.error('構成リクエストに失敗しました:', error.code, error.message);
console.log('適用したボタンスタイル:control');
} finally {
// これは単発スクリプト。常駐サービスでは、アプリケーション終了時のみ共有Clientを閉じる。
await client.close();
}
}
main().catch(function (error) {
console.error(error);
process.exitCode = 1;
});
常駐サービスでは、各プロセス内でプロジェクトとサービスURLごとにClientを再利用してください。各業務リクエストで現在のユーザー識別情報を渡し、リクエストごとにClientを作成・終了しないでください。また、異なるユーザー間でFeatureを再利用しないでください。client.optionsは正規化済みの読み取り専用構成であり、client.closedは終了処理が開始されたかを示します。
3.2 既存のデータ収集インスタンスを再利用する
業務で公式Node.jsデータ収集SDKを導入済みの場合は、既存インスタンスのConsumer、バッチ処理、定期フラッシュの構成を維持してください。データ収集インスタンスの初期化が完了した後、同じインスタンスをtdAnalyticsに渡します。
const { createClient, SplitMode } = require('td-feature-node');
// existingAnalyticsは、業務で初期化済みのtrack/flush/closeを持つインスタンス。
const client = createClient({
appId: 'YOUR_APP_ID',
serverUrl: 'https://YOUR_SERVER_URL',
splitMode: SplitMode.REMOTE,
tdAnalytics: existingAnalytics,
});
インスタンスを注入しない場合、SDKは最初のインプレッション時に、同じappIdとserverUrlを使用して公式のBatchデータ収集インスタンスを遅延作成します。
3.3 ESMとTypeScript
ESMプロジェクトでは、デフォルトインポートでCommonJSパッケージを使用します。次の例はインポートの記述方法です。それ以外の呼び出しはasync関数内に配置してください。
import sdk from 'td-feature-node';
const { createClient, SplitMode } = sdk;
TypeScriptプロジェクトでは、APIと公開型を直接インポートできます。コンパイラのバージョンは業務プロジェクトに合わせてください。
import { createClient, SplitMode } from 'td-feature-node';
import type { ClientOptions, FeatureRequest } from 'td-feature-node';
const options: ClientOptions = {
appId: 'YOUR_APP_ID',
serverUrl: 'https://YOUR_SERVER_URL',
splitMode: SplitMode.REMOTE,
};
const client = createClient(options);
const request: FeatureRequest = {
accountId: 'user_123',
featureKeys: ['checkout_button'],
};
3.4 初期化構成リファレンス
3.4.1 接続とリクエスト
| 構成 | デフォルト値 | 説明 |
|---|---|---|
| appId | 必須 | プロジェクトのApp ID。空でない文字列。 |
| serverUrl | 必須 | リモート判定とSDKが作成するデータ収集インスタンスで共用するHTTP(S)のベースURL。 |
| splitMode | SplitMode.REMOTE | 文字列REMOTEも指定できます。LOCALは現在未対応です。 |
| timeout | 5000 ms | HTTP試行ごとのタイムアウト。 |
| maxHttpConnections | 20 | RCC接続プールの最大接続数。 |
| tlsCa | Nodeのデフォルト信頼ルート | 任意のPEM CA文字列または配列。明示的に指定すると、このClientのデフォルトCAリストを置き換えます。 |
3.4.2 再試行
| 構成 | デフォルト値 | 説明 |
|---|---|---|
| retryTimes | 0 | 初回リクエスト後の追加再試行回数。範囲は0から10。 |
| retryStrategy | EXPONENTIAL_BACKOFF | FIXED_INTERVALも選択できます。 |
| retryInterval | 500 ms | 最初のバックオフ間隔。0も指定できます。 |
3.4.3 結果キャッシュ
| 構成 | デフォルト値 | 説明 |
|---|---|---|
| enableCache | false | 成功した結果のキャッシュを明示的に有効化します。 |
| cacheExpireTime | 86400秒 | RCC TTLが0以下の場合にのみフォールバックとして使用します。0も指定できます。 |
| maxCacheSize | 10000 | 結果キャッシュの最大エントリ数。0は保存しないことを意味します。 |
3.4.4 インプレッションとデータ収集
| 構成 | デフォルト値 | 説明 |
|---|---|---|
| autoExposure | false | 元の値または型付きの値が最初に読み取られたときに、インプレッションの送信を試みます。 |
| exposureDedupMaxSize | 100000 | インプレッション重複排除の最大エントリ数。 |
| exposureDedupExpireSeconds | 86400秒 | アクセスで延長されない重複排除TTL。 |
| tdAnalytics | 未指定 | 業務で使用中の公式データ収集インスタンス。業務側が保持して終了処理を行います。 |
| exposureAdapter | 未指定 | カスタムデータ収集アダプタ。tdAnalyticsとは排他的であり、業務側が保持します。 |
3.4.5 プライベートCAとカスタムデータ収集
プライベートCAを使用する場合、信頼する証明書を明示的に渡せます。証明書チェーンとホスト名の検証は引き続き有効です。tlsCaはRCCとSDKが作成する収集インスタンスのみに影響し、外部インスタンスは自身のTLS構成を引き続き使用します。
const fs = require('fs');
const { createClient } = require('td-feature-node');
const client = createClient({
appId: 'YOUR_APP_ID',
serverUrl: 'https://YOUR_SERVER_URL',
tlsCa: fs.readFileSync('/path/to/trusted-ca.pem', 'utf8'),
});
4. 構成と実験情報の取得
4.1 現在のユーザー識別情報を渡す
| リクエストパラメータ | 意味 | 使用要件 |
|---|---|---|
| accountId | #account_idに対応するアカウントID | アカウント単位でトラフィック分割する場合は、安定した正確なアカウント識別子を渡してください。 |
| distinctId | #distinct_idに対応するゲストIDまたはデバイスID | ゲスト単位でトラフィック分割する場合は、管理画面の定義と一致する識別子を渡してください。 |
accountIdとdistinctIdの少なくとも一方が空でない文字列である必要があります。両方を渡すこともできます。数値IDは業務側で明示的に文字列へ変換してください。識別情報に制御文字を含めることはできません。
4.2 1つまたは複数のFeatureを取得する
client.fetch(request, options?)はPromise<Evaluation>を返します。以降の部分的な例で使用するclientは、第3節で作成した共有Clientです。awaitの呼び出しはasync関数内に配置してください。1つのKeyでも複数のKeyでもfeatureKeys配列を使用します。
const config = await client.fetch({
accountId: 'user_123',
distinctId: 'visitor_456',
featureKeys: ['checkout_button', 'recommendation_enabled'],
});
const feature = config.features['checkout_button'];
4.3 異なる型の構成値を読み取る
| 管理画面の変数型 | 読み取りメソッド | 戻り値の型とフォールバックルール |
|---|---|---|
| 文字列 | feature.asString(defaultValue) | string。null以外の値を文字列に変換し、オブジェクトと配列はJSONテキストに変換します。 |
| 数値 | feature.asNumber(defaultValue) | number。数値または空でない数値文字列を受け付け、ネイティブのNumber()で変換します。 |
| 真偽値 | feature.asBoolean(defaultValue) | boolean。真偽値と、大文字・小文字を区別しないtrue/false文字列を受け付けます。数値の0/1は変換しません。 |
| JSONオブジェクト | feature.asJson(defaultValue) | JSONオブジェクト。オブジェクト、またはオブジェクトとして解析可能なJSON文字列を受け付けます。配列、null、不正なJSONはフォールバックします。 |
| 元の値 | feature.value | 配列とnullを含む元のJSON値。 |
const config = await client.fetch({
accountId: 'user_123',
featureKeys: ['recommendation_enabled', 'discount_rate', 'page_config'],
});
const enabledFeature = config.features['recommendation_enabled'];
const enabled = enabledFeature ? enabledFeature.asBoolean(false) : false;
const rateFeature = config.features['discount_rate'];
const rate = rateFeature ? rateFeature.asNumber(0) : 0;
const defaults = { theme: 'default' };
const pageFeature = config.features['page_config'];
const page = pageFeature ? pageFeature.asJson(defaults) : defaults;
4種類の型の読み取りメソッドでは、デフォルト値を省略するとnullを返します。値がnullの場合や変換できない場合は、渡されたデフォルト値を使用します。構成が存在しない場合と変換に失敗した場合は、個別に処理してください。false、0、空文字列は有効な値です。value || defaultValueで上書きしないでください。
4.4 実験情報を取得する
const feature = config.features['checkout_button'];
if (feature) {
console.log('Feature Key:', feature.key);
console.log('値の有無:', feature.hasValue);
const info = feature.experiment;
if (info && info.experimentId && info.experimentGroupId) {
console.log('実験ID:', info.experimentId);
console.log('グループID:', info.experimentGroupId);
console.log('対照群かどうか:', info.isControlGroup);
console.log('バケットの識別情報:', info.bucketId);
}
}
4.5 現在のリクエストで取得可能なすべての構成を取得する
const all = await client.fetch({
accountId: 'user_123',
distinctId: 'visitor_456',
});
const keys = Object.keys(all.features);
console.log(keys);
console.log(all.ttl); // RCCの元のTTL。単位は秒で、キャッシュの残り有効期間ではない。
featureKeysを省略した場合、nullを渡した場合、空配列を渡した場合は、現在の識別情報とリクエスト条件に基づいてサーバーから返されるすべての構成を取得します。
4.6 カスタムリクエストパラメータ
const config = await client.fetch({
accountId: 'user_123',
featureKeys: ['checkout_button'],
customParams: {
vip_level: 3,
channel: 'app_store',
country: 'CN',
},
});
customParamsはJSONオブジェクトです。パラメータ名、型、意味は管理画面のルールに一致させる必要があります。文字列、有限の数値、真偽値、null、配列、ネストしたオブジェクトに対応しています。undefined、Date、BigInt、関数、NaN、Infinity、循環参照は受け付けません。オブジェクトと配列内のnullは維持されます。#account_id、#distinct_id、#lib、#feature_keyはSDKが管理するため、カスタムパラメータでは上書きできません。カスタムパラメータの指定は、新しい振り分け主体の設定ではありません。
5. インプレッションイベントの送信
インプレッションは、実験構成が実際に業務で使用されたことを意味します。fetchの成功、Featureの取得、実験メタ情報の確認だけでは、インプレッションが発生したことにはなりません。SDKはデータ収集インスタンスを通じてte_experiment_exposureを送信し、#experiment_id、#experiment_group_id、#is_control_group、#rule_type="experiment"を付加します。現在のリモート解析で提供されていないFeatureバージョンやトラフィック分割元などのフィールドを、イベントに補って作成することはありません。
5.1 手動インプレッション(デフォルト)
デフォルトはautoExposure: falseです。業務で構成を実際に適用した後、今回返されたFeatureオブジェクトをexpose()に渡してください。引数はFeature Key文字列ではありません。
const feature = config.features['checkout_button'];
const style = feature.asString('control');
console.log('業務で適用済みの値:', style); // 実際の業務ロジックに置き換える。
const accepted = client.expose(feature, { scene: 'checkout', channel: 'web' });
console.log('インプレッションのキュー登録結果:', accepted);
5.2 自動インプレッション(任意)
const client = createClient({
appId: 'YOUR_APP_ID',
serverUrl: 'https://YOUR_SERVER_URL',
autoExposure: true,
});
const config = await client.fetch({
accountId: 'user_123',
featureKeys: ['checkout_button'],
});
const feature = config.features['checkout_button'];
const style = feature ? feature.asString('control') : 'control';
有効にすると、feature.valueの最初の読み取り、またはasString/asNumber/asBoolean/asJsonの最初の呼び出しで、インプレッション送信を試みます。有効な実験情報があることが前提です。返された各Featureが自動トリガーするのは最大1回で、その後Client単位の重複排除が適用されます。キャッシュヒット時は、自動トリガー状態が独立した新しいFeatureが返されます。
5.3 重複排除、非同期送信、フラッシュ
- 現在のClientのメモリ内で「振り分け主体 + 実験ID + グループID」により重複を排除します。主体はbucketIdの最初の空でない項目を優先し、次にaccountId、distinctIdの順に選びます。Feature Keyは重複排除に使用されません。同じ実験グループ内の複数のFeatureは、1回のインプレッションを共有します。
- 重複排除は常に有効です。デフォルトの上限は100000件、TTLは86400秒で、読み取りによる延長はありません。有効期限切れ、容量超過による削除、Clientの再作成、プロセスの再起動後には、再送信される場合があります。
- インプレッションは上限付きの非同期キューで送信されます。デフォルトでは10000件の待機枠と1件の実行中タスクがあります。SDKが作成する収集インスタンスは、デフォルトで100件ずつ送信し、1バッチに満たない場合は最大1000 msバッファに保持します。
6. 構成の非同期取得
6.1 async/awaitとPromise
async function readStyle(accountId) {
try {
const config = await client.fetch({
accountId: accountId,
featureKeys: ['checkout_button'],
});
const feature = config.features['checkout_button'];
return feature ? feature.asString('control') : 'control';
} catch (error) {
console.error('構成リクエストに失敗しました:', error.code);
return 'control';
}
}
client.fetch({ accountId: 'user_123', featureKeys: ['checkout_button'] })
.then(function (config) {
const feature = config.features['checkout_button'];
console.log(feature ? feature.asString('control') : 'control');
})
.catch(function (error) {
console.error(error.code, error.message);
});
上の非同期取得の例はクエリのみを示しており、デフォルトではインプレッションを送信しません。返された値を実際に適用する箇所に、第5節に従ってインプレッションの呼び出しを追加してください。
6.2 タイムアウト、再試行、同時実行
- timeoutのデフォルトは5000 msで、接続待機とレスポンスの読み取りを含む各HTTP試行のみを制限します。キュー待機、再試行のバックオフ、RCCフィールドのデコードは、このHTTPタイムアウトには含まれません。再試行を有効にした場合、各試行で計測し直します。
- retryTimesのデフォルトは0で、自動再試行は行いません。明示的に正の数を指定すると、最大試行回数は1 + retryTimesになります。一時的なネットワークエラー、1回の試行のタイムアウト、HTTP 408/429/500/502/503/504は、回数を制限して再試行できます。RCCの業務エラー、不正なレスポンス、恒久的なDNS・証明書エラーなどは再試行しません。
- デフォルトでは最大20件のfetchを同時実行でき、待機キューはありません(maxQueueSize: 0)。同時実行枠が埋まると、直ちにQUEUE_FULLで拒否されます。maxQueueSizeを明示的に正の数にした場合にのみ、上限付きFIFOキューが有効になり、待機枠が埋まった場合も拒否されます。キャッシュヒット時はキューを使用せず、直接結果を返します。

