본문으로 건너뛰기

Java

최근 업데이트 2026. 10. 27.

최신 버전: 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 데이터 수집 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와 서비스 주소별로 애플리케이션 내에서 싱글턴으로 재사용해야 합니다. 각 요청마다 현재 사용자의 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
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);

네 가지 타입의 읽기 메서드는 모두 인자가 없는 오버로드를 제공합니다. 값이 없거나 변환할 수 없으면 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();
이 문서가 도움이 되었나요?