실험 React Native SDK(레거시)

기존 SDK는 더 이상 사용되지 않을 때까지 버그 수정만 받습니다. SDK 통합, React Native Web, Expo 등을 지원하는 v1.0.0+로 업그레이드하는 것이 좋습니다.

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

설치

웹 호환성

실험용 React Native SDK는 iOS 및 Android React Native 프로젝트와만 호환됩니다. JavaScript SDK를 사용하여 세 가지 플랫폼을 모두 지원하십시오.

실험 JavaScript Client SDK를 설치합니다.

npm install --save @amplitude/experiment-react-native-client

빠른 시작

실험 클라이언트 초기화
사용자를 위한 변형 가져오기
플래그 변형에 액세스

// (1) Initialize the experiment client
await Experiment.initialize('<DEPLOYMENT_KEY>');
// (2) Fetch variants for a user
const user = {
    user_id: 'user@company.com',
    device_id: 'abcdefg',
    user_properties: {
        'premium': true,
    },
};
await Experiment.fetch(user);
// (3) Lookup a flag's variant
const variant = await Experiment.variant('<FLAG_KEY>');
if (variant.value === 'on') {
    // Flag is on
} else {
    // Flag is off
}

핵심 기능

다음 기능은 실험 클라이언트측 SDK의 핵심을 구성합니다.

비동기 함수

Native SDK는 내부적으로 실행되므로 모든 함수의 await 결과가 필요합니다.

초기화

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

initialize(apiKey: string, config?: ExperimentConfig): Promise<boolean>

매개 변수	요구 사항	설명
`apiKey`	필수	가져오기 요청을 승인하고 사용자에 대해 평가할 플래그를 결정하는 배포 키입니다.
`config`	선택 사항	SDK 클라이언트 동작을 사용자 정의하는 데 사용되는 클라이언트 구성입니다.

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

const experiment = await Experiment.initialize('<DEPLOYMENT_KEY>');

통합

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

Amplitude 연동 Amplitude 실험 SDK

는 Amplitude 애널리틱스 SDK와 연동되도록 설정되어 있습니다. SDK 버전을 최신 버전으로 업데이트하고 특별한 연동 초기화 기능을 사용하십시오.

await Amplitude.getInstance().init('<API_KEY>');
await Experiment.initializeWithAmplitudeAnalytics('<DEPLOYMENT_KEY>');

분석에 사용자 지정 인스턴스 이름을 사용하는 경우 실험 SDK의 instanceName의구성 옵션에서 동일한 값을 설정하십시오.

연동 초기화기는 사용자 제공자 및 노출 추적 제공자 인터페이스의 구현을 구성하여 Amplitude 애널리틱스 SDK에서 사용자 데이터를 가져오고 노출 이벤트를 추적합니다.

지원되는 버전

분석 SDK 버전	실험 SDK 버전
`2.8.0+`	`0.6.0+`

구성

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

이름	설명	기본값
`debug`	SDK 내에서 추가 디버그 로깅을 활성화합니다. 프로덕션 빌드에서는 false로 설정되어야 합니다.	`false`
`fallbackVariant`	제공된 키에 대한 변형이 존재하지 않을 경우 폴백할 기본 변형입니다.	`{}`
`initialVariants`	액세스할 변형의 초기 세트입니다. 이 필드는 서버 측 렌더링(SSR)을 사용하여 서버에서 렌더링한 값으로 클라이언트 SDK를 부트스트랩하는 데 도움이 됩니다.	`{}`
`serverUrl`	변형을 가져올 호스트입니다.	`https://api.lab.amplitude.com`
`fetchTimeoutMillis`	변형을 가져오는 데 필요한 시간 초과(밀리초)입니다.	`10000`
`retryFetchOnFailure`	요청이 성공하지 못할 경우 백그라운드에서 변형 가져오기를 재시도할지 여부입니다.	`true`
`automaticExposureTracking`	true인 경우 `variant()`를 호출하면 설정된 `exposureTrackingProvider`를 통해 노출 이벤트를 추적합니다. 노출 추적 공급자가 설정되어 있지 않은 경우 이 구성 옵션은 아무 작업도 수행하지 않습니다.	`true`
`automaticFetchOnAmplitudeIdentityChange`	`initializeWithAmplitudeAnalytics`초기화 기능을 사용하여 Amplitude 애널리틱스 SDK와 연동하는 경우에만 중요합니다.`true` 분석에서 사용자 ID, 기기 ID 또는 사용자 속성에 어떠한 변경이라도 발생하면 실험 SDK가 변형을 가져오고 캐시를 업데이트하도록 트리거합니다.	`false`
`userProvider`	호출 시 사용자 객체를 `fetch()`에 제공하는 데 사용되는 인터페이스입니다.	`null`
`exposureTrackingProvider`	이 인터페이스를 구현하고 구성하여 실험 SDK를 통해 노출 이벤트를 자동으로 또는 명시적으로 추적하십시오.	`null`
`instanceName`	실험 SDK 인스턴스의 사용자 지정 인스턴스 이름입니다. 이 필드의 값은 대소문자를 구분합니다.	`null`

EU 데이터 센터

Amplitude의 EU 데이터 센터를 사용하는 경우, 초기화 시 serverUrl 옵션을 https://api.lab.eu.amplitude.com

(으)로 구성하십시오.

가져오기

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

fetch(user?: ExperimentUser): Promise<boolean>

매개 변수	요구 사항	설명
`user`	선택 사항	평가 요청과 함께 전달할 명시적 사용자 정보입니다. SDK는 이 사용자 정보를 사용자 공급자를 통한 통합에서 제공된 사용자 정보와 병합하며, 제공된 속성보다 `fetch()`에 명시적으로 전달된 속성을 선호합니다.

Amplitude는 사용자가 애플리케이션 세션에 대한 최신 변형을 얻을 수 있도록 애플리케이션 시작 시 fetch()를 호출할 것을 권장합니다. 또한 사용자 환경을 렌더링하기 전에 가져오기 요청이 결과를 반환할 때까지 기다려야 인터페이스의 "깜박임"을 방지할 수 있습니다.

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

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

await Experiment.fetch();

사용자 ID가 변경될 때 가져오기

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

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

시간 초과 및 재시도

fetch() 시간이 초과되거나(기본 10초) 어떤 이유로든 실패하는 경우, SDK 클라이언트는 제어권을 반환하고 백오프를 사용하여 백그라운드에서 재시도합니다. SDK 클라이언트 초기화 중에 구성 옵션에서 시간 초과를 구성하거나 재시도를 비활성화할 수 있습니다.

변형

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

자동 노출 추적

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

variant(key: string): Promise<Variant>

variantWithFallback(key: string, fallback: Variant): Promise<Variant>

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

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

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

변형의 페이로드에 액세스하십시오.

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

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

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

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

모두

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

all(): Promise<Variants>

노출:

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

exposure(key: string): Promise<boolean>

매개 변수	요구 사항	설명
`key`	필수	노출 이벤트를 추적할 플래그 또는 실험 변형을 식별하는 플래그 키입니다.

const variant = await Experiment.variant('<FLAG_KEY>');
// Do other things...
await Experiment.exposure('<FLAG_KEY>');
if (variant === 'control') {
    // Control
} else if (variant === 'treatment') {
    // Treatment
}

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