For AI agents: a documentation index is available at /docs/llms.txt. Append .md to any page URL for markdown, or send Accept: text/markdown.
실험 JVM SDK
Amplitude Experiment의 서버측 JVM SDK 구현에 대한 공식 문서입니다. 이 SDK는 Java 또는 Kotlin 서버측 구현에서 사용하십시오.
이 문서에는 원격 및 로컬 평가에 대한 섹션이 별도로 제공됩니다.
원격 평가
원격 평가를 사용하여 사용자의 변형 가져오기를 구현합니다.
설치
Gradle을 사용하여 JVM Server SDK를 설치합니다.
implementation "com.amplitude:experiment-jvm-server:<VERSION>"
원격 초기화
서버 시작 시 서버에서 SDK 클라이언트를 초기화합니다.apiKey 매개변수에 전달하는 배포 키 인수는 분석 이벤트를 전송하는 동일한 프로젝트 내에 있어야 합니다.
fun initializeRemote(
apiKey: String,
config: RemoteEvaluationConfig = RemoteEvaluationConfig()
): RemoteEvaluationClient
val experiment = Experiment.initializeRemote("<DEPLOYMENT_KEY>")
구성
초기화 시 SDK 클라이언트를 구성합니다.
EU 데이터 센터
Amplitude의 EU 데이터 센터를 사용하는 경우, 초기화 시 serverZone 옵션을 구성하십시오.
| 이름 | 설명 | 기본값 |
|---|---|---|
debug | 디버그 로깅을 활성화하려면 true로 설정하십시오. | false |
logLevel | 출력할 최소 로그 수준입니다. 옵션: VERBOSE, DEBUG, INFO, WARN, ERROR, DISABLE. 사용자 지정 로깅으로 이동합니다. | ERROR |
loggerProvider | 맞춤형 로거 구현. 사용자의 LoggerProvider 로깅 솔루션과 통합할 수 있는 인터페이스를 구현하십시오. 사용자 지정 로깅으로 이동합니다. | DefaultLogger 명령어는 stdout에 출력합니다 |
serverZone | 사용할 Amplitude 데이터 센터입니다. ServerZone.US 또는 ServerZone.EU. | ServerZone.US |
serverUrl | 플래그 구성을 가져올 호스트입니다. | https://api.lab.amplitude.com |
fetchTimeoutMillis | 변형을 가져오는 데 필요한 시간 초과(밀리초)입니다. | 500 |
fetchRetries | 변형 가져오기 요청이 실패할 경우 시도할 재시도 횟수입니다. | 1 |
fetchRetryBackoffMinMillis | 변형 가져오기 요청이 실패한 이후의 최소한(초기) 백오프입니다. SDK는 fetchRetryBackoffScalar에 따라 이 지연을 조정합니다. | 0 |
fetchRetryBackoffMaxMillis | 재시도 간의 최대 백오프입니다. 스케일링된 백오프가 최대값보다 커지면 SDK는 모든 후속 요청에 대해 최대값을 사용합니다. | 10000 |
fetchRetryBackoffScalar | 최소 백오프를 기하급수적으로 확장합니다. | 1 |
CohortSyncConfig
| 이름 | 설명 | 기본값 |
|---|---|---|
apiKey | 분석 API 키이며 실험 배포 키가 아닙니다. | 필수 |
secretKey | 분석 비밀 키 | 필수 |
maxCohortSize | SDK가 다운로드할 수 있는 코호트의 최대 크기입니다. 이 크기보다 큰 코호트는 다운로드되지 않습니다. | 2147483647 |
cohortPollingIntervalMillis | 코호트 업데이트를 위해 Amplitude를 폴링하는 간격(밀리초 단위)입니다(최소 60000). | 60000 |
cohortServerUrl | 코호트 데이터를 가져올 원본인 코호트 서버 엔드포인트입니다. EU 데이터 센터를 사용하려면 serverZone로ServerZone.EU 설정하십시오. 이 값을 설정하면 serverZone 기본값보다 우선하여 적용됩니다. | https://cohort-v2.lab.amplitude.com |
가져오기
사용자의 변형을 가져오고 결과를 반환합니다. 원격으로 평가 함수는 SDK 클라이언트를 초기화하는 데 사용된 배포와 관련된 플래그에 대해 사용자를 평가합니다.
fun fetch(user: ExperimentUser, fetchOptions: FetchOptions? = null): CompletableFuture<Map<String, Variant>>
FetchOptions
| 이름 | 설명 | 기본값 |
|---|---|---|
tracksExposure | 이 가져오기 요청에 대한 노출 이벤트를 추적할지 여부입니다. null인 경우 서버의 기본 동작을 사용합니다(노출을 추적하지 않음). | null |
tracksAssignment | 이 가져오기 요청에 대한 할당 이벤트를 추적할지 여부입니다. null인 경우 서버의 기본 동작을 사용합니다(트랙 할당 수행). | null |
val user = ExperimentUser.builder()
.userId("user@company.com")
.deviceId("abcdefg")
.userProperty("premium", true)
.build()
val variants = try {
experiment.fetch(user).get()
} catch (e: Exception) {
e.printStackTrace()
return
}
사용자의 변형을 가져온 후에는 특정 플래그의 변형에 액세스할 수도 있습니다.
val variant = variants["<FLAG_KEY>"]
if (variant?.value == "on") {
// Flag is on
} else {
// Flag is off
}
지역 평가
로컬 평가를 사용하여 사용자에 대한 변형 평가를 구현합니다. 로컬 평가를 사용하려는 경우 장단점을 이해해야 합니다.
설치
Maven 또는 Gradle을 사용하여 JVM Server SDK를 설치합니다.
implementation "com.amplitude:experiment-jvm-server:<VERSION>"
빠른 시작
// (1) Initialize the local evaluation client with a server deployment key.
val experiment = Experiment.initializeLocal(
"<DEPLOYMENT_KEY>",
// (Recommended) Enable local evaluation cohort targeting.
LocalEvaluationConfig.builder()
.cohortSyncConfig(CohortSyncConfig("<API_KEY>", "<SECRET_KEY>"))
.build()
)
// (2) Start the local evaluation client.
experiment.start()
// (3) Evaluate a user.
val user = ExperimentUser.builder()
.userId("user@company.com")
.deviceId("abcdefg")
.userProperty("premium", true)
.build()
val variants = experiment.evaluate(user)
로컬 초기화
로컬 평가 클라이언트를 초기화합니다.
fun initializeLocal(
apiKey: String,
config: LocalEvaluationConfig = LocalEvaluationConfig(),
): LocalEvaluationClient
구성
초기화 시 SDK 클라이언트를 구성할 수 있습니다.
EU 데이터 센터
Amplitude의 EU 데이터 센터를 사용하는 경우, 초기화 시 serverZone 옵션을 구성하십시오.
LocalEvaluationConfig
| 이름 | 설명 | 기본값 |
|---|---|---|
debug | 디버그 로깅을 활성화하려면 true로 설정하십시오. | false |
logLevel | 출력할 최소 로그 수준입니다. 옵션: VERBOSE, DEBUG, INFO, WARN, ERROR, DISABLE. 사용자 지정 로깅으로 이동합니다. | ERROR |
loggerProvider | 맞춤형 로거 구현. 사용자의 LoggerProvider 로깅 솔루션과 통합할 수 있는 인터페이스를 구현하십시오. 사용자 지정 로깅으로 이동합니다. | DefaultLogger 명령어는 stdout에 출력합니다 |
serverZone | 사용할 Amplitude 데이터 센터입니다. ServerZone.US 또는 ServerZone.EU. | ServerZone.US |
serverUrl | 플래그 구성을 가져올 호스트입니다. | https://api.lab.amplitude.com |
flagConfigPollingIntervalMillis | Start() 호출 후 업데이트된 플래그 구성을 폴링하는 간격 | 30000 |
flagConfigPollerRequestTimeoutMillis | 플래그 구성 폴러에 의해 생성된 요청에 대한 시간 초과 | 10000 |
assignmentConfiguration | 더 이상 사용되지 않습니다. 로컬 평가에 대한 자동 할당 추적을 활성화합니다. | null |
exposureConfiguration | 로컬 평가를 위해 노출 추적을 활성화합니다. | null |
streamUpdates | 스트리밍을 활성화하여 플래그 구성 업데이트를 수신하기 위한 폴링을 대체합니다. Amplitude 서버는 매 초마다 폴링하는 대신 일반적으로 1초 이내에 SDK에 업데이트를 푸시합니다. 어떤 이유로든 스트림이 실패할 경우 자동으로 폴링으로 되돌아가며 일정 간격을 두고 스트리밍을 재시도합니다. | false |
streamServerUrl | 스트림 서버의 URL입니다. | https://stream.lab.amplitude.com |
streamFlagConnTimeoutMillis | 유효한 플래그 구성 스트림을 설정하기 위한 시간 초과입니다. 여기에는 스트림 서버와의 연결을 설정하는 시간과 초기 플래그 설정을 수신하는 시간이 포함됩니다. | 1500 |
cohortSyncConfig | 로컬 평가 코호트 타겟팅을 위해 코호트 다운로드를 활성화하는 구성입니다. | null |
할당구성
노출구성
CohortSyncConfig
| 이름 | 설명 | 기본값 |
|---|---|---|
apiKey | 분석 API 키이며 실험 배포 키가 아닙니다. | 필수 |
secretKey | 분석 비밀 키 | 필수 |
maxCohortSize | SDK가 다운로드할 수 있는 코호트의 최대 크기입니다. 이 크기보다 큰 코호트는 다운로드되지 않습니다. | 2147483647 |
cohortPollingIntervalMillis | 코호트 업데이트를 위해 Amplitude를 폴링하는 간격(밀리초 단위)입니다(최소 60000). | 60000 |
시작
로컬 평가 클라이언트를 시작하여 평가를 위한 로컬 평가 모드 플래그 구성을 미리 가져오고 구성된 간격에 따라 플래그 구성 폴러를 시작합니다.
fun start()
start()이(가) 반환될 때까지 기다린 후 evaluate()를 호출하여 평가 시 플래그 구성을 사용할 수 있는지 확인하십시오.
중지
로컬 평가 클라이언트를 종료하여 플래그 구성 및 코호트를 업데이트하기 위한 백그라운드 프로세스를 중단합니다.
fun stop()
평가
start()에서 미리 가져온 플래그를 사용하여 평가 로직을 실행합니다. evaluate에 사용자 객체 인수를 지정해야 합니다. 플래그 변형의 특정 하위 집합만 필요한 경우 선택적으로 플래그 키 배열을 전달할 수 있습니다.
노출 추적
노출 추적을 활성화하려면 exposureConfiguration을 설정하십시오. 그런 다음 evaluate()을 호출할 때 EvaluateOptions의 tracksExposure을 true(으)로 설정하십시오.
fun evaluate(user: ExperimentUser, flagKeys: List<String> = listOf(), evaluateOptions: EvaluateOptions? = null): Map<String, Variant>
// The user to evaluate
val user = ExperimentUser.builder()
.userId("user@company.com")
.deviceId("abcdefg")
.userProperty("premium", true)
.build()
// Evaluate all flag variants
val allVariants = experiment.evaluate(user)
// Evaluate a specific subset of flag variants
val specificVariants = experiment.evaluate(user, listOf(
"<FLAG_KEY_1>",
"<FLAG_KEY_2>",
))
// Access a variant
val variant = allVariants["<FLAG_KEY>"]
if (variant?.value == "on") {
// Flag is on
} else {
// Flag is off
}
평가 옵션
| 이름 | 설명 | 기본값 |
|---|---|---|
tracksExposure | true인 경우 SDK는 평가된 변형에 대한 노출 이벤트를 추적합니다. | false |
로컬 평가 코호트 타겟팅
버전 1.4.0부터 로컬 평가 SDK 클라이언트는 로컬 평가 타겟팅을 위한 코호트 다운로드를 지원합니다. 이 지원을 활성화하려면 초기화 시 분석 apiKey 및 secretKey와 함께 cohortSyncConfig를 사용하여 SDK를 구성하십시오.
val experiment = Experiment.initializeLocal(
"<DEPLOYMENT_KEY>",
// (Recommended) Enable local evaluation cohort targeting.
LocalEvaluationConfig.builder()
.cohortSyncConfig(CohortSyncConfig("<API_KEY>", "<SECRET_KEY>"))
.build()
)
사용자 지정 로깅
로그 세부 정보를 조정하려면 logLevel 구성을 설정하거나, 자체 로거를 사용하려면 LoggerProvider 인터페이스를 구현하십시오.
로그 수준
VERBOSE: 자세한 디버깅 로그DEBUG: 개발 및 문제 해결 로그INFO: 일반 정보WARN: 경고ERROR: 오류만 (기본값)DISABLE: 로그 없음
사용자 지정 로거
사용자 고유의 로깅 솔루션을 사용하기 위해 LoggerProvider 인터페이스를 구현하십시오.
import com.amplitude.experiment.util.LogLevel
import com.amplitude.experiment.util.LoggerProvider
class MyCustomLogger : LoggerProvider {
override fun verbose(msg: String) {
// Implement verbose logging
}
override fun debug(msg: String) {
// Implement debug logging
}
override fun info(msg: String) {
// Implement info logging
}
override fun warn(msg: String) {
// Implement warn logging
}
override fun error(msg: String) {
// Implement error logging
}
}
// Initialize with custom logger
val experiment = Experiment.initializeLocal(
"<DEPLOYMENT_KEY>",
LocalEvaluationConfig.builder()
.logLevel(LogLevel.DEBUG)
.loggerProvider(MyCustomLogger())
.build()
)
이전 버전과의 호환성
debug 구성 필드는 여전히 지원됩니다. true로 설정된 경우 logLevel를 DEBUG로 재정의합니다.
이 내용이 도움이 되었나요?