Java
최신 버전: v1.0.0
업데이트 날짜: 2026-10-27
1. 개요
6.1 버전부터 AE에 실험 키트 기능이 추가되었습니다. AE 콘솔에서 실험을 만들고 대조군과 실험 그룹의 변수 값을 설정한 후, SDK를 통해 실험 관련 정보를 가져와 그룹별 사용자에게 서로 다른 콘텐츠를 표시할 수 있습니다.
이 문서는 Java 서버단 SDK의 통합 과정을 설명합니다. ThinkingData SDK와의 상호작용에만 집중하면 되며, AE 콘솔의 작업 세부 사항은 처리할 필요가 없습니다.
Java 서버단 실험 SDK는 AE 실험의 Feature 설정을 가져오는 데 사용됩니다. 비즈니스 서비스가 현재 사용자 식별자와 필요한 Feature Key를 전달하면 설정 센터(RCC)에서 원격 분기를 수행하고, SDK가 설정값과 일치한 실험 정보를 반환합니다. 비즈니스 서비스는 설정에 따라 로직을 실행하고, 설정이 실제 비즈니스에 사용된 후 노출 이벤트를 전송합니다.
- Feature Key는 AE 콘솔에서 설정한 변수 식별자입니다. 예시에서는 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 데이터 수집 SDK | 3.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와 서비스 주소별로 애플리케이션 내에서 싱글턴으로 재사용해야 합니다. 각 요청마다 현재 사용자의 FeatureRequest를 별도로 만듭니다. serverUrl에는 설정 조회와 데이터 수집을 모두 지원하는 서비스 루트 주소를 입력하고, 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 | 방문자를 기준으로 분기하는 실험에서는 AE 콘솔 정의와 일치하는 방문자 ID를 전달합니다. |
accountId와 distinctId 중 하나 이상의 비어 있지 않은 값을 전달해야 하며, 둘 다 전달할 수도 있습니다. ID가 하나 있다는 것만으로 실험과의 일치가 보장되지는 않습니다. 실제로 전달한 식별 정보가 AE 콘솔의 분할 단위 및 타겟 사용자 조건을 충족해야 합니다. 사용자가 바뀌면 새 요청에 새 사용자의 식별자를 전달합니다. 서로 다른 사용자 간에 FeatureResult를 재사용하지 마세요.
4.2 하나 이상의 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");
단일 Key에는 featureKey("checkout_button")을, 여러 Key에는 featureKeys(...)를 사용합니다. 가변 인자와 List<String>을 지원합니다. 전송 및 결과 처리 비용을 줄이도록 비즈니스에 필요한 Key를 요청하는 것을 권장합니다. getFeature(key)는 반환된 결과에 해당 Key가 없으면 null을 반환합니다.
4.3 타입별 설정값 읽기
| AE 콘솔의 변수 타입 | 읽기 메서드 | 반환 타입 |
|---|---|---|
| 문자열 | getValueAsString(defaultValue) | String |
| 숫자 | getValueAsDouble(defaultValue) | Double |
| 불리언 | getValueAsBoolean(defaultValue) | Boolean |
| JSON | getValueAsJson(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);
네 가지 타입의 읽기 메서드는 모두 인자가 없는 오버로드를 제공합니다. 값이 없거나 변환할 수 없으면 null을 반환하고, 인자가 있는 오버로드는 전달된 기본값을 반환합니다. JSON은 Fastjson2의 JSONObject를 사용합니다. 불리언 읽기는 Boolean 값과 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()는 유효한 실험 정보가 포함되어 있는지를 나타냅니다. 실험과 일치하지 않아도 AE 콘솔의 기본값을 받을 수 있으며, 이 경우 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)으로 파라미터 하나를 추가하거나 customParams(Map<String, Object>)로 여러 파라미터를 한 번에 전달할 수 있습니다. 파라미터 이름, 타입, 의미는 AE 콘솔의 설정 채널 및 규칙 정의와 일치해야 합니다. 식별 정보, SDK 식별자, Key 필터링은 각각 전용 파라미터로 관리됩니다. 사용자 지정 파라미터로 #account_id, #distinct_id, #lib, #feature_key를 덮어쓰지 마세요. 사용자 지정 요청 파라미터는 새 분할 단위를 설정하는 것이 아닙니다.
5. 노출 이벤트 전송
노출은 실험 설정이 비즈니스에 실제로 사용되었음을 의미합니다. fetch를 시작하거나 FeatureConfig가 반환되거나 실험 메타데이터를 확인하는 것만으로는 설정이 비즈니스에 사용되었다고 볼 수 없습니다. SDK는 데이터 수집 인스턴스를 통해 실험, 그룹, Feature 등의 정보가 포함된 te_experiment_exposure 이벤트를 전송합니다.
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();

