メインコンテンツまでスキップ

Java

最終更新 2026/10/27

最新バージョン:v1.0.0

更新日:2026-10-27

1. 概要​

AEはバージョン6.1から実験スイートを提供しています。AE管理画面で実験を作成し、対照群とテストグループの変数値を構成して、SDKで実験情報を取得することで、グループごとのユーザーに異なるコンテンツを表示できます。

本ドキュメントでは、JavaサーバーサイドSDKの導入方法を説明します。ThinkingAI SDKとのやり取りに集中すればよく、AE管理画面のタスクの詳細を意識する必要はありません。

Javaサーバーサイド実験SDKは、AE実験のFeature構成を取得します。業務サービスが現在のユーザー識別子と必要なFeature Keyを渡すと、構成センター(RCC)がリモートトラフィック分割を行い、SDKが構成値と割り当てられた実験の情報を返します。業務サービスは構成に基づいてロジックを実行し、構成が実際に業務で使用された後にインプレッションイベントを送信します。

  • Feature Keyは管理画面で構成する変数の識別子です。例ではcheckout_buttonを使用しています。導入時にプロジェクトで実際に使用するKeyに置き換えてください。
  • クライアントの初期化後、現在のユーザーの実験構成は自動取得されません。業務サービスからfetch(FeatureRequest)またはfetch(accountId, distinctId)を呼び出してリクエストします。
  • 実験に割り当てられなくても、Featureのデフォルト構成値が返される場合があります。

2. SDKの導入​

2.1 環境と依存関係​

JDK 8以上が必要です。SDKはMaven Centralで公開されています。必要な推移的依存関係も解決できるよう、MavenまたはGradleによる自動導入を推奨します。

<dependency>
<groupId>cn.thinkingdata</groupId>
<artifactId>td-feature-java</artifactId>
<version>1.0.0</version>
</dependency>

Gradleの例:

repositories {
mavenCentral()
}

dependencies {
implementation 'cn.thinkingdata:td-feature-java:1.0.0'
}

Maven座標のgroupIdはcn.thinkingdataです。Javaパッケージ名は引き続きcn.thinkingai.featureを使用します。POMで宣言されている実行時依存関係は次のとおりです。

依存関係用途1.0.0のPOMで宣言されているバージョン
thinkingdatasdkインプレッションの送信に使用するJavaデータ収集SDK3.0.6
httpclient構成センターへのアクセス4.5.14
caffeine構成キャッシュとインプレッションの重複排除2.9.3
slf4j-apiロギングAPI。ログの実装は業務プロジェクトで提供1.7.36
guava / re2j / commons-codec基本的な依存関係31.1-jre / 1.8 / 1.14

これらの依存関係はSDKとともに推移的に導入されるため、通常は個別に追加する必要はありません。

3. 初期化とクイックスタート​

3.1 完全な例:​

次の例ではSDKのデフォルト構成を使用します。SDKがデータ収集インスタンスを自動作成し、現在のユーザーに表示可能なすべてのFeatureを取得します。getFeatureKeys()ですべてのKeyを取得した後、checkout_buttonを選んで業務に適用し、インプレッションを手動送信します。TDFeatureClientはApp IDとサービスURLごとにアプリケーション内でシングルトンとして再利用し、各リクエストで現在のユーザー用のFeatureRequestを個別に作成してください。serverUrlには構成クエリとデータ収集の両方に対応するサービスのルートURLを指定し、App ID、ユーザー識別子、業務用Keyを実際の値に置き換えてください。

import cn.thinkingai.feature.api.FeatureConfig;
import cn.thinkingai.feature.api.FeatureRequest;
import cn.thinkingai.feature.api.FeatureResult;
import cn.thinkingai.feature.api.SplitMode;
import cn.thinkingai.feature.api.TDFeatureClient;
import cn.thinkingai.feature.common.Config;
import java.util.Collections;
import java.util.Set;

public class RemoteSplitQuickStart {
public static void main(String[] args) throws Exception {
String appId = "YOUR_APP_ID";
TDFeatureClient client = new TDFeatureClient(Config.builder()
.appId(appId)
.serverUrl("https://YOUR_SERVER_URL")
.splitMode(SplitMode.REMOTE)
.build());

try {
String buttonStyle = "control"; // 業務のデフォルト値
FeatureResult feature = null;
try {
FeatureConfig config = client.fetch(FeatureRequest.builder()
.accountId("user_123")
.distinctId("visitor_456")
// featureKey/featureKeysを指定せず、現在のユーザーに表示可能なすべての構成を取得
.build());

Set<String> featureKeys = config.getFeatureKeys();
System.out.println("今回返されたすべてのFeature Key:" + featureKeys);

feature = config.getFeature("checkout_button");
if (feature != null && feature.hasValue()) {
buttonStyle = feature.getValueAsString("control");
}
} catch (RuntimeException e) {
// リクエスト失敗時は業務のデフォルト値を使用し、ログを記録
System.err.println("構成リクエストに失敗しました:" + e.getMessage());
}
} finally {
// 実際のサービスではアプリケーション終了時のみ実行。リクエスト終了ごとにシングルトンを閉じない
client.close();
}
}
}

3.2 既存のTDAnalyticsインスタンス​

業務でJavaデータ収集SDK(TDAnalytics)を導入済みの場合は、既存のデータ収集SDKの初期化、Consumer、送信構成を維持してください。データ収集SDKの初期化完了後、業務で保持している同じTDAnalyticsシングルトンをtdAnalytics(...)に渡してから実験SDKを作成します。データ収集インスタンスを作り直す必要はありません。

import cn.thinkingai.feature.api.SplitMode;
import cn.thinkingai.feature.api.TDFeatureClient;
import cn.thinkingai.feature.common.Config;
import cn.thinkingdata.analytics.TDAnalytics;

public class ExistingAnalyticsIntegration {
public static TDFeatureClient createFeatureClient(
String appId, String rccServerUrl, TDAnalytics analytics) {
if (analytics == null) {
throw new IllegalArgumentException("業務で使用中のTDAnalyticsインスタンスを渡してください");
}

return new TDFeatureClient(Config.builder()
.appId(appId)
.serverUrl(rccServerUrl)
.splitMode(SplitMode.REMOTE)
.tdAnalytics(analytics) // 既存のデータ収集SDKを再利用
.build());
}
}

4. 構成と実験情報の取得​

4.1 現在のユーザー識別情報を渡す​

リクエストパラメータ意味使用要件
accountId#account_idに対応するアカウントIDアカウント単位でトラフィック分割する実験には、正確で安定したアカウントIDを渡してください。
distinctId#distinct_idに対応するゲストIDゲスト単位でトラフィック分割する実験には、管理画面の定義と一致するゲストIDを渡してください。

accountIdとdistinctIdの少なくとも一方に空でない値を渡してください。両方を渡すこともできます。単にIDが1つあれば実験に割り当てられるわけではありません。実際に渡す識別情報は、管理画面の振り分け主体とグループ条件を満たす必要があります。ユーザーが切り替わった場合は、新しいリクエストで新しいユーザーの識別子を渡してください。FeatureResultを異なるユーザー間で再利用しないでください。

4.2 1つまたは複数のFeatureを取得する​

FeatureConfig config = client.fetch(FeatureRequest.builder()
.accountId("user_123")
.featureKeys("checkout_button", "recommendation_enabled", "discount_rate", "page_config")
.build());

FeatureResult button = config.getFeature("checkout_button");
String buttonStyle = button == null
? "control" : button.getValueAsString("control");

1つのKeyにはfeatureKey("checkout_button")、複数のKeyにはfeatureKeys(...)を使用します。可変長引数とList<String>に対応しています。転送と結果処理の負荷を減らすため、業務で必要なKeyをリクエストすることを推奨します。getFeature(key)は、返された結果にそのKeyがない場合、nullを返します。

4.3 異なる型の構成値を読み取る​

管理画面の変数型読み取りメソッド戻り値の型
文字列getValueAsString(defaultValue)String
数値getValueAsDouble(defaultValue)Double
真偽値getValueAsBoolean(defaultValue)Boolean
JSONgetValueAsJson(defaultValue)com.alibaba.fastjson2.JSONObject
元の値getValue()Object
FeatureConfig config = client.fetch(FeatureRequest.builder()
.accountId("user_123")
.featureKeys("recommendation_enabled", "discount_rate", "page_config")
.build());

FeatureResult enabledFeature = config.getFeature("recommendation_enabled");
boolean enabled = enabledFeature == null
? false : enabledFeature.getValueAsBoolean(false);

FeatureResult rateFeature = config.getFeature("discount_rate");
double rate = rateFeature == null ? 0.0 : rateFeature.getValueAsDouble(0.0);

JSONObject defaults = new JSONObject();
defaults.put("theme", "default");
FeatureResult pageFeature = config.getFeature("page_config");
com.alibaba.fastjson2.JSONObject page = pageFeature == null
? defaults : pageFeature.getValueAsJson(defaults);

4種類の型の読み取りメソッドには、いずれも引数なしのオーバーロードがあります。値がない場合や変換できない場合はnullを返し、引数ありのオーバーロードでは指定したデフォルト値を返します。JSONにはFastjson2のJSONObjectを使用します。真偽値の読み取りは真偽値型とtrue/false文字列を認識し、それ以外の値にはデフォルト値を使用します。構成リクエストの失敗時にスローされる例外は、業務側で処理する必要があります。型のデフォルト値は、ネットワーク例外の処理を代替するものではありません。

4.4 実験情報を取得する​

if (feature != null && feature.isExperimentMatched()) {
ExperimentInfo info = feature.getExperimentInfo();
String experimentId = info.fetchId();
String groupId = info.fetchGroupId();
boolean controlGroup = info.isControlGroup();
String featureKey = feature.getFeatureKey();
String featureVersion = feature.getFeatureVersion();
}

hasValue()は現在のFeatureに値があるか、isExperimentMatched()は有効な実験情報が含まれているかを示します。実験に割り当てられていない場合でも管理画面のデフォルト値が返されることがあり、その場合getExperimentInfo()はnullになります。実験情報の読み取りだけを行う場合や、hasValue()/isExperimentMatched()を呼び出す場合、自動インプレッションはトリガーされません。

4.5 現在のリクエストで取得可能なすべての構成を取得する​

FeatureConfig all = client.fetch("user_123", "visitor_456");
Set<String> keys = all.getFeatureKeys();

Feature Keyを指定しない場合は、現在の識別情報とリクエスト条件に基づいてサーバーから返されるすべての構成を取得します。

4.6 カスタムリクエストパラメータ​

FeatureConfig config = client.fetch(FeatureRequest.builder()
.accountId("user_123")
.featureKey("checkout_button")
.customParam("vip_level", 3)
.customParam("channel", "app_store")
.build());

customParam(key, value)でパラメータを1つ追加できます。customParams(Map<String, Object>)で一括して渡すこともできます。パラメータ名、型、意味は、管理画面の構成チャンネルとルール定義に一致させてください。識別情報、SDK識別子、Keyの絞り込みは、それぞれ専用パラメータで管理します。カスタムパラメータで#account_id、#distinct_id、#lib、#feature_keyを上書きしないでください。カスタムリクエストパラメータの指定は、新しい振り分け主体の設定ではありません。

5. インプレッションイベントの送信​

インプレッションは、実験構成が実際に業務で使用されたことを意味します。fetchの実行、FeatureConfigの取得、実験メタ情報の確認だけでは、構成が業務で使用されたことにはなりません。SDKはデータ収集インスタンスを通じてte_experiment_exposureイベントを送信し、実験、グループ、Featureなどの情報を付加します。

5.1 手動インプレッション(デフォルト)​

初期化時はautomaticExposureTracking(false)を維持してください。業務で構成を実際に適用した後、今回取得したFeatureResultを渡します。インプレッションAPIの引数は結果オブジェクトであり、Feature Key文字列ではありません。

// featureは今回の現在のユーザーのfetch結果から取得する必要がある
// この時点より前に、業務でこのFeatureの構成値を実際に使用していること
if (feature != null && feature.hasValue() && feature.isExperimentMatched()) {
Map<String, Object> properties = new HashMap<>();
properties.put("scene", "checkout");
client.exposure(feature, properties);
// カスタムプロパティが不要な場合はclient.exposure(feature)を使用
}

カスタムインプレッションプロパティでは、#で始まるプロパティ名はSDKの予約名であり、渡しても無視されます。SDKは有効な実験情報がない結果をスキップします。

5.2 自動インプレッション(任意)​

automaticExposureTrackingをtrueにすると、結果のgetValue()またはgetValueAsString/Double/Boolean/Json(...)を最初に読み取ったときに、自動インプレッションがトリガーされます。ただし、その結果が実験に割り当てられていることが前提です。

TDFeatureClient automaticClient = new TDFeatureClient(Config.builder()
.appId("YOUR_APP_ID")
.serverUrl("https://YOUR_RCC_SERVER")
.splitMode(SplitMode.REMOTE)
.tdAnalytics(analytics)
.automaticExposureTracking(true)
.build());

// automaticClientはアプリケーション内で再利用し、アプリケーション終了時のみclose()を呼び出す
FeatureConfig config = automaticClient.fetch(FeatureRequest.builder()
.accountId("user_123")
.featureKey("checkout_button")
.build());
FeatureResult result = config.getFeature("checkout_button");
String value = result == null ? "control" : result.getValueAsString("control");
// 実験に割り当てられている場合、上の値の読み取りでインプレッションがトリガーされる

5.3 重複排除、非同期送信、フラッシュ​

インプレッションはSDKのバックグラウンドキューで非同期処理されます。exposure(...)から戻っても、イベントがデータベースに保存済みとは限りません。デフォルトでは、現在のClientのメモリキャッシュ内で「振り分け主体 + 実験ID + グループID」により重複を排除します。最大100000件のマーカーを保持し、デフォルトの有効期間は86400秒です。重複排除キャッシュの容量超過による削除、Clientの再作成、プロセスの再起動後には、再送信される場合があります。

// トラブルシューティング、短時間のタスク終了時、アプリケーション終了前に必要に応じて呼び出す
client.flush();

flush()は、それまでに受け付けたインプレッションタスクを待機し、データ収集SDKのflushを呼び出します。

6. 構成の非同期取得​

非同期オーバーロードでもFeatureRequestを渡す必要があります。非同期スレッド数のデフォルトは5、待機キュー容量のデフォルトは1000です。キューが満杯の場合やClientが閉じられている場合はRejectedExecutionExceptionが発生します。業務のデフォルト値にフォールバックし、例外を記録してください。

6.1 Future形式​

FeatureRequest request = FeatureRequest.builder()
.accountId("user_123")
.featureKey("checkout_button")
.build();

Future<FeatureConfig> future = client.fetchAsync(request);
String value = "control";
try {
FeatureConfig config = future.get(2, TimeUnit.SECONDS);
FeatureResult result = config.getFeature("checkout_button");
if (result != null) {
value = result.getValueAsString("control");
}
} catch (InterruptedException e) {
Thread.currentThread().interrupt();
} catch (java.util.concurrent.TimeoutException
| java.util.concurrent.ExecutionException e) {
// 失敗を記録し、valueは業務のデフォルト値を維持
System.err.println("非同期取得に失敗しました:" + e.getMessage());
}

6.2 コールバック形式​

client.fetchAsync(FeatureRequest.builder()
.accountId("user_123")
.featureKey("checkout_button")
.build(), new FeatureCallback() {
@Override
public void onSuccess(FeatureConfig config) {
FeatureResult result = config.getFeature("checkout_button");
String value = result == null
? "control" : result.getValueAsString("control");
// 業務で使用するために構成を渡す。実際の使用後に手動インプレッションをトリガー
}

@Override
public void onFailure(Exception e) {
// 失敗を記録し、業務のデフォルト値を継続して使用
System.err.println("非同期取得に失敗しました:" + e.getMessage());
}
});

7. 構成キャッシュ​

構成キャッシュはデフォルトで無効です。enableCache(true)を有効にすると、同じ有効リクエストの後続呼び出しで、キャッシュされた構成の戻り値を再利用できます。リクエストの識別情報、Feature Keyの集合、カスタムリクエストパラメータはいずれもキャッシュの区別に使用されます。キャッシュはバックグラウンドポーリングではありません。キャッシュが有効な間は呼び出しに対して直接結果を返し、キャッシュ失効後の次のリクエストで再びRCCにアクセスします。

TDFeatureClient cachedClient = new TDFeatureClient(Config.builder()
.appId("YOUR_APP_ID")
.serverUrl("https://YOUR_RCC_SERVER")
.splitMode(SplitMode.REMOTE)
.tdAnalytics(analytics)
.enableCache(true)
.cacheExpireTime(300)
.maxCacheSize(10000)
.build());

// 現在のClientの構成キャッシュのみをクリア
cachedClient.clearCache();
このページは役に立ちましたか?