이 페이지에서

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.

실험 JavaScript SDK.

npmv1.23.120.5 kB gzip

Amplitude Experiment의 클라이언트 측 JavaScript SDK 구현에 대한 공식 문서입니다.

설치

다음 세 가지 방법 중 하나를 사용하여 실험 JavaScript Client SDK를 설치하십시오.

통합 SDK

브라우저 통합 SDK를 설치하여 실험 SDK와 다른 Amplitude 제품(분석, 세션 리플레이)에 액세스하십시오. 통합 SDK는 모든 Amplitude 기능을 위한 단일 진입점을 제공하며, 모든 구성 요소의 초기화 및 구성을 처리함으로써 연동 프로세스를 단순화합니다.

# Install Experiment SDK only
npm install --save @amplitude/experiment-js-client
# Or install Unified SDK to get access to all Amplitude products
npm install @amplitude/unified

빠른 시작

: 실험 SDK를 초기화하는 올바른 방법은 분석을 위해 Amplitude SDK를 사용하는지 아니면 제3자(예: 세그먼트)를 사용하는지에 따라 다릅니다.

  1. 실험 클라이언트 초기화
  2. 변형 가져오기
  3. 플래그 변형에 액세스
typescript
import { Experiment } from '@amplitude/experiment-js-client';
// (1) Initialize the experiment client with Amplitude Analytics.
const experiment = Experiment.initializeWithAmplitudeAnalytics(
    'DEPLOYMENT_KEY'
);
// (2) Fetch variants and await the promise result.
await experiment.fetch();
// (3) Lookup a flag's variant.
const variant = experiment.variant('FLAG_KEY');
if (variant.value === 'on') {
    // Flag is on
} else {
    // Flag is off
}

초기화

시작 시 애플리케이션에서 SDK를 초기화합니다. 매개변수에 전달하는 apiKey배포 키 인수는 이벤트를 전송할 대상과 동일한 Amplitude 프로젝트에 있어야 합니다.

initializeWithAmplitudeAnalytics(apiKey: string, config?: ExperimentConfig): ExperimentClient
매개 변수설명
apikey_필수_입니다. 가져오기 요청을 승인하고 사용자에 대해 평가할 플래그를 결정하는 배포 키
configSDK 클라이언트 동작을 사용자 정의하기 위한 클라이언트 구성입니다.

초기화기는 단일 인스턴스를 반환하므로 동일한 인스턴스 이름에 대한 후속 초기화는 항상 초기 인스턴스를 반환합니다. 여러 인스턴스를 생성하려면 instanceName 구성을 사용하십시오.

import { Experiment } from '@amplitude/experiment-js-client';
const experiment = initializeWithAmplitudeAnalytics('DEPLOYMENT_KEY');

구성

초기화 시 SDK 클라이언트를 구성합니다.

통합

Amplitude 또는 Segment Analytics SDK를 사용하여 이벤트를 Amplitude로 추적하는 경우, 초기화 시 연동을 설정하십시오. 연동은 공급자 인터페이스를 자동으로 구현하여 사용자 ID 관리와 노출 이벤트 추적을 보다 쉽게 함으로써 보다 간소화된 개발자 환경을 제공합니다.

사용자 동의 관리

실험 SDK는 동의 API를 노출하지 않습니다. consentOptions구성, ConsentStatus 유형 또는 setConsentStatus() 방법은 없습니다.

GDPR 스타일의 동의 흐름을 지원하려면 동의 관리 플랫폼(CMP)의 신호에 따라 Amplitude 초기화 및 변형 가져오기를 제어하십시오. 사용자가 동의할 때까지 분석 SDK를 초기화하거나 fetch() 또는 start()를 호출하지 마십시오.

typescript
import * as amplitude from '@amplitude/analytics-browser';
import { Experiment } from '@amplitude/experiment-js-client';
// Call this only after your CMP reports that the user granted consent.
async function onConsentGranted() {
    amplitude.init('API_KEY');
    const experiment = Experiment.initializeWithAmplitudeAnalytics('DEPLOYMENT_KEY');
    await experiment.fetch();
}

사용자가 동의를 철회할 경우 호출을 중단하고 fetch()를 사용하여 저장된 전체 변형을 지웁니다clear().

가져오기

사용자의 변형을 가져오고 빠른 액세스를 위해 결과를 클라이언트에 저장합니다. 원격으로 평가 함수는 SDK 클라이언트를 초기화하는 데 사용된 배포와 관련된 플래그에 대해 사용자를 평가합니다.

사용자 ID 변경 시 가져오기

사용자에 대한 최신 변형을 원한다면, 사용자 상태가 fetch()의미 있는 방식으로 변경될 때마다 호출하는 것이 좋습니다. 예를 들어 사용자가 로그인하여 사용자 ID를 받거나, 플래그 또는 실험 타겟팅 규칙에 영향을 줄 수 있는 사용자 속성이 설정되어 있는 경우가 있습니다.

원격 평가 전에 사용자 보강에 의존하지 않고 새 사용자 속성을 명시적으로 fetch()에 전달하십시오. 별도의 시스템을 통한 원격 사용자 속성 동기화는 fetch()에 대한 타이밍을 보장하지 않으며, 이는 경합 조건을 야기할 수 있습니다.

typescript
fetch(user?: ExperimentUser, options?: FetchOptions): Promise<Client>
매개 변수요구 사항설명
user선택 사항평가 요청과 함께 전달할 명시적 사용자 정보입니다. SDK는 이 사용자 정보를 사용자 공급자를 통한 통합에서 제공된 사용자 정보와 병합하며, 제공된 속성보다 fetch()에 명시적으로 전달된 속성을 선호합니다.
options선택 사항가져올 명시적 플래그 키입니다.

typescript
const user = {
    user_id: 'user@company.com',
    device_id: 'abcdefg',
    user_properties: {
        'premium': true,
    },
};
await experiment.fetch(user);

연동 또는 사용자 지정 사용자 제공자를 사용하는 경우 사용자를 입력하지 않고도 가져올 수 있습니다.

typescript
await experiment.fetch();

fetch()시간이 초과되거나 어떤 이유로든 실패하면 SDK 클라이언트가 반환되며 백오프를 사용하여 백그라운드에서 재시도합니다. SDK 클라이언트 초기화 다음 기간동안 구성 옵션에서 시간 초과를 구성하거나 재시도를 비활성화할 수 있습니다.

시작

Fetch 대 start

클라이언트 측 로컬 평가를 사용하는 경우 start를 사용하십시오. 원격 평가만 사용하는 경우에는 start 대신 fetch 를 호출하십시오.

서버에서 플래그 구성을 가져오고 사용자를 위한 원격 평가 변형을 가져와서 SDK를 시작합니다. 반환된 promise가 완료되면 SDK가 준비된 상태입니다.

typescript
start(user?: ExperimentUser): Promise<void>
매개 변수요구 사항설명
user선택 사항변형 가져오기 요청과 함께 전달할 명시적 사용자 정보입니다. SDK는 이 사용자 정보를 사용자 공급자를 통해 통합에서 제공된 사용자 정보와 병합하며, 제공된 속성보다 명시적으로 전달된 속성을 fetch()선호합니다. 또한 SDK에서 사용자를 재사용할 수 있도록 설정합니다.

애플리케이션이 초기화될 start()때 사용자 정보를 사용하여 변형을 평가하거나 가져올 수 있게 된 후에 호출하십시오. 로컬 평가 플래그 구성을 로드하고 원격 평가 변형을 가져온 후 프로미스가 완료됩니다.

초기화 시 SDK 구성에서 start()설정을 통해 fetchOnStart의 동작을 구성하여 애플리케이션의 요구에 따라 성능을 향상시킵니다.

  • 응용 프로그램이 원격 평가에 의존하지 않는 경우 원격 평가로 인한 스타트업 지연 시간 증가를 방지하려면 false로 설정하십시오fetchOnStart.
  • 애플리케이션이 원격 평가에 의존하지만 스타트업 직후에는 그렇지 않은 경우 fetchOnStart을 false로 설정하고 별도로 fetch()를 호출하여 프로미스를 기다릴 수 있습니다.
await experiment.start();

변형

SDK 클라이언트의 로컬 스토어에서 플래그 또는 실험에 대한 변형에 액세스하십시오.

자동 노출 추적

연동을 사용하거나 사용자 지정 노출 추적 공급자를 설정할 경우, variant()는 추적 공급자를 통해 노출 이벤트를 자동으로 추적합니다. 이 기능을 비활성화하려면 구성에서 automaticExposureTracking를 false로 설정하고, exposure()를 사용하여 노출을 수동으로 추적하십시오.

typescript
variant(key: string, fallback?: string | Variant): Variant
매개 변수요구 사항설명
key필수변형에 액세스하기 위한 플래그 또는 실험을 식별하기 위한 플래그 키입니다.
fallback선택 사항지정된 flagKey에 대해 변형을 찾을 수 없을 경우 반환할 값입니다.

사용자가 어떤 변형으로 분류되었는지 확인할 때 변형 value을 잘 알려진 문자열과 비교해야 할 것입니다.

typescript
const variant = experiment.variant('<FLAG_KEY>');
if (variant.value === 'on') {
    // Flag is on
} else {
    // Flag is off
}

변형의 페이로드에

액세스변형은 임의의 데이터의 동적 페이로드로 구성될 수도 있습니다. 변형의 value을 확인한 후 변형 객체에서 payload 필드에 액세스합니다.

typescript
const variant = experiment.variant('<FLAG_KEY>');
if (variant.value === 'on') {
    const payload = variant.payload;
}

null 변형 value은 사용자가 변형으로 분류되지 않았음을 의미합니다. 저장소에 지정된 플래그 키에 대한 변형이 없는 경우 내장된 폴백 매개변수를 사용하여 반환할 변형을 제공할 수 있습니다.

typescript
const variant = experiment.variant('<FLAG_KEY>', { value: 'control' });
if (variant.value === 'control') {
    // Control
} else if (variant.value === 'treatment') {
    // Treatment
}

모두

SDK 클라이언트에 저장된 모든 변형에 액세스합니다.

typescript
all(): Variants

지우기

캐시와 스토리지의 모든 변형을 지웁니다.

typescript
clear(): void

사용자가 로그아웃한 후 clear 를 호출하여 캐시와 저장소의 변형을 지울 수 있습니다.

typescript
experiment.clear();

노출:

구성된 연동 또는 사용자 지정 노출 추적 공급자를 통해 지정된 플래그 키의 현재 변형에 대한 노출 이벤트를 수동으로 추적합니다. 일반적으로 automaticExposureTracking의 구성 옵션을 false로 설정하는 것과 함께 사용됩니다.

typescript
exposure(key: string): void
매개 변수요구 사항설명
key필수노출 이벤트를 추적할 플래그 또는 실험 변형을 식별하는 플래그 키입니다.
typescript
const variant = experiment.variant('<FLAG_KEY>');
// Do other things...
experiment.exposure('<FLAG_KEY>');
if (variant.value === 'control') {
    // Control
} else if (variant.value === 'treatment') {
    // Treatment
}

공급자

연동 실험 클라이언트 SDK와 함께 Amplitude 또는 세그먼트 분석 SDK를 사용하는 경우, Amplitude는 사용자 지정 공급자를 구현하는 대신 연동을 사용하는 것을 권장합니다.

공급자 구현은 사용자 ID를 관리하고 노출 이벤트를 추적하기가 더 쉬워짐으로써 개발자 환경을 더욱 간소화할 수 있게 해줍니다.

사용자 제공자

SDK 클라이언트는 사용자 제공자를 사용하여 필요한 경우에만 최신 사용자 정보에 액세스합니다(예: fetch() 가 호출될 때). 사용자 공급자는 선택 사항이지만 응용 프로그램에 사용자 정보 저장소가 이미 설정되어 있는 경우 유용합니다. 사용자 공급자를 사용하면 두 개의 개별 사용자 정보 저장소를 동시에 관리할 필요가 없습니다. 애플리케이션 사용자 저장소가 업데이트되었지만 실험이 업데이트되지 않은 경우(또는 그 반대의 경우)에 별도의 저장소가 서로 일치하지 않는 사용자 상태를 생성할 수 있습니다.

typescript
interface ExperimentUserProvider {
  getUser(): ExperimentUser;
}

사용자 지정 사용자 공급자를 사용하려면 SDK 초기화 시 사용자 지정 구현의 인스턴스로 userProvider의 구성 옵션을 설정하십시오.

typescript
const experiment = Experiment.initialize('<DEPLOYMENT_KEY>', {
    userProvider: new CustomUserProvider(),
});

노출 추적 공급자

Amplitude는 노출 추적 공급자를 구현할 것을 강력히 권장합니다. 노출 추적은 실험 결과의 정확성과 신뢰성을 높이고 사용자가 어떤 플래그와 실험에 노출되었는지에 대한 가시성을 개선합니다.

typescript
export interface ExposureTrackingProvider {
  track(exposure: Exposure): void;
}

track()의 구현은 flag_key 및 variant 이라는 두 개의 이벤트 속성을 사용하여 $exposure유형(이름이라고도 함)의 이벤트를 추적해야 하며, 이는 Exposure객체 인수의 두 필드에 해당합니다. 마지막으로, 추적된 이벤트는 SDK 클라이언트를 초기화하는 데 사용된 [배포]가 첫 사용 후 동일한 프로젝트에 대해 결국 Amplitude 애널리틱스에 기록되어야 하며, 변형을 가져온 것과 동일한 사용자에 대해 발생해야 합니다.

사용자 지정 사용자 공급자를 사용하려면 SDK 초기화 시 사용자 지정 구현의 인스턴스로 exposureTrackingProvider의 구성 옵션을 설정하십시오.

typescript
const experiment = Experiment.initialize('<DEPLOYMENT_KEY>', {
    exposureTrackingProvider: new CustomExposureTrackingProvider(),
});

부트스트랩

변형이 외부 소스(예: SDK 클라이언트에서 fetch()을(를) 호출하여 가져온 것이 아닌 경우)에서 온 경우 초기 플래그 또는 변형 세트를 사용하여 실험 클라이언트를 부트스트랩할 수 있습니다. 사용 사례로는 로컬 평가, 서버 측 렌더링 또는 특정 변형에 대한 연동 테스트가 포함됩니다.

부트스트랩 변형

미리 정의된 변형 집합으로 클라이언트를 부트스트랩하려면 initialVariants의 구성 객체에서 플래그와 변형을 설정한 다음 source를 Source.InitialVariants로 설정하십시오. 그러면 SDK 클라이언트가 동일한 플래그에 대해 이전에 인출되고 저장된 변형보다 부트스트랩된 변형을 선호합니다.

typescript
const experiment = Experiment.initialize('<DEPLOYMENT_KEY>', {
    // Map flag keys to variant objects. The variant object may either be
    // pre-evaluation (SSR) or input manually in for testing.
    initialVariants: {
        "<FLAG_KEY>": {
            "value": "<VARIANT>"
         }
    },
    source: Source.InitialVariants,
});

부트스트랩 플래그 구성

구성을 통해 초기 로컬 평가 플래그 구성 세트로 SDK를 부트스트랩하도록 선택할 수 있습니다initialFlags. 업데이트된 플래그 구성 또는 변형이 start 또는 fetch로 로드되지 않은 경우 SDK는 변형이 호출될 때 이러한 플래그 구성을 평가합니다.

초기 플래그를 다운로드하려면 평가 플래그 API를 사용하십시오.

typescript
const experiment = Experiment.initialize('<DEPLOYMENT_KEY>', {
    initialFlags: "<FLAGS_JSON>",
});

HTTP 클라이언트

사용자 지정 HTTP 클라이언트 구현을 제공하여 SDK에서 수행한 네트워크 요청을 처리할 수 있습니다. 이 기능은 특정 네트워킹 요구 사항이 있는 환경이나 요청 처리를 사용자 정의해야 할 때 유용합니다.

typescript
export interface SimpleResponse {
  status: number;
  body: string;
}
export interface HttpClient {
  request(
    requestUrl: string,
    method: string,
    headers: Record<string, string>,
    data: string,
    timeoutMillis?: number,
  ): Promise<SimpleResponse>;
}

사용자 지정 HTTP 클라이언트를 사용하려면 SDK 초기화 시 구현 인스턴스를 사용하여 httpClient의 구성 옵션을 설정하십시오.

typescript
const experiment = Experiment.initialize('<DEPLOYMENT_KEY>', {
    httpClient: new CustomHttpClient(),
});

사용자 지정 로깅

구성을 통해 로그 세부 정보를 제어하거나 Logger인터페이스를 구현하여 자체 logLevel로깅 솔루션을 통합하십시오.

로그 수준

  • LogLevel.Disable - 로깅 없음
  • LogLevel.Error - 오류만(기본값)
  • LogLevel.Warn - 오류 및 경고
  • LogLevel.Info - 오류, 경고 및 정보 메시지
  • LogLevel.Debug - 오류, 경고, 정보 및 디버그 메시지
  • LogLevel.Verbose - 자세한 내용을 포함한 모든 메시지
typescript
import { Experiment, LogLevel } from '@amplitude/experiment-js-client';
// Only log errors
const experiment = Experiment.initialize('<DEPLOYMENT_KEY>', {
  logLevel: LogLevel.Error
});
// Log errors and warnings
const experiment = Experiment.initialize('<DEPLOYMENT_KEY>', {
  logLevel: LogLevel.Warn
});
// Log everything (verbose)
const experiment = Experiment.initialize('<DEPLOYMENT_KEY>', {
  logLevel: LogLevel.Verbose
});

사용자 지정 로거

사용자 고유의 로깅 솔루션을 사용하기 위해 Logger 인터페이스를 구현하십시오.

typescript
import { Experiment, Logger, LogLevel } from '@amplitude/experiment-js-client';
// Implement the Logger interface
class CustomLogger implements Logger {
  error(message?: any, ...optionalParams: any[]): void {
    // Send errors to your logging service
    myLoggingService.error(message, ...optionalParams);
  }
  warn(message?: any, ...optionalParams: any[]): void {
    myLoggingService.warn(message, ...optionalParams);
  }
  info(message?: any, ...optionalParams: any[]): void {
    myLoggingService.info(message, ...optionalParams);
  }
  debug(message?: any, ...optionalParams: any[]): void {
    myLoggingService.debug(message, ...optionalParams);
  }
  verbose(message?: any, ...optionalParams: any[]): void {
    myLoggingService.verbose(message, ...optionalParams);
  }
}
// Initialize with custom logger
const experiment = Experiment.initialize('<DEPLOYMENT_KEY>', {
  loggerProvider: new CustomLogger(),
  logLevel: LogLevel.Warn
});

디버그 플래그(사용되지 않음)

debug이 구성 플래그는 사용되지 않습니다. 대신 logLevel을 사용하십시오.

typescript
// Deprecated: Sets logLevel to Debug
const experiment = Experiment.initialize('<DEPLOYMENT_KEY>', {
  debug: true
});
// Preferred: Use logLevel instead
const experiment = Experiment.initialize('<DEPLOYMENT_KEY>', {
  logLevel: LogLevel.Debug
});

이 내용이 도움이 되었나요?