실험 Flutter SDK

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

설치

pubspec.yaml패키지를 다음amplitude_experiment에 추가하십시오:

dependencies:
  amplitude_experiment: ^1.0.0

그런 다음 실행하십시오:

flutter pub get

웹 설치(선택 사항)

Flutter 실험 SDK는 Dart의 JavaScript 상호 운용성을 사용하여 Flutter 웹용 실험 JavaScript SDK를 활성화합니다. 이를 위해서는 SDK를 글로벌 JavaScript 범위 첫 사용 후 사용할 수 있도록 해야 합니다. Flutter 프로젝트의 web/index.html 에 다음 스크립트 태그를 추가하세요:

<script src="https://unpkg.com/@amplitude/experiment-js-client@1.21.3/dist/experiment.umd.js"></script>

import 'package:amplitude_flutter/amplitude.dart';
import 'package:amplitude_flutter/configuration.dart';
import 'package:amplitude_experiment/amplitude_experiment.dart';
// (1) Initialize the Amplitude Analytics SDK.
final amplitude = Amplitude(Configuration(apiKey: 'API_KEY'));
await amplitude.isBuilt;
// (2) Initialize the experiment client with Amplitude Analytics.
final experiment = await Experiment.initializeWithAmplitude(
  'DEPLOYMENT_KEY',
  ExperimentConfig(),
);
// (3) Fetch variants and await the result.
await experiment.fetch();
// (4) Look up a flag's variant.
final variant = await experiment.variant('FLAG_KEY');
if (variant.value == 'on') {
  // Flag is on
} else {
  // Flag is off
}

초기화

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

static Future<ExperimentClient> initializeWithAmplitude(String apiKey, ExperimentConfig config)

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

import 'package:amplitude_flutter/amplitude.dart';
import 'package:amplitude_flutter/configuration.dart';
import 'package:amplitude_experiment/amplitude_experiment.dart';
final amplitude = Amplitude(Configuration(apiKey: 'API_KEY'));
await amplitude.isBuilt;
final experiment = await Experiment.initializeWithAmplitude(
  'DEPLOYMENT_KEY',
  ExperimentConfig(),
);

구성

SDK 클라이언트 구성은 초기화 다음 기간동안 수행됩니다.

• logLevel
  • 설명: 출력할 최소 로그 레벨입니다. 옵션: LogLevel.none, LogLevel.error, LogLevel.warn, LogLevel.info, LogLevel.debug, LogLevel.verbose.
  • 기본값: LogLevel.warn
• fallbackVariant
  • 설명: 제공된 키에 대한 변형이 존재하지 않을 경우 폴백할 기본 변형입니다.
  • 기본값: null
• initialVariants
  • 설명: 액세스할 변형의 초기 세트입니다. 이 필드는 서버 측 렌더링(SSR)을 사용하여 서버에서 렌더링한 값으로 클라이언트 SDK를 부트스트랩하는 데 도움이 됩니다.
  • 기본값: {}
• source
  • 설명: 변형의 기본 소스입니다. 값을 Source.initialVariants 설정하고 SSR 또는 테스트 목적으로 SDK를 부트스트랩하도록 initialVariants구성합니다.
  • 기본값: Source.localStorage
• serverZone
  • 설명: 플래그와 변형을 가져올 Amplitude 데이터 센터를 us 또는 eu에서 선택합니다.
  • 기본값: ServerZone.us
• serverUrl
  • 설명: 원격 평가 변형을 가져올 호스트입니다. EU 데이터 센터를 방문하려면 serverZone을 사용하십시오.
  • 기본값: https://api.lab.amplitude.com
• flagsServerUrl
  • 설명: 로컬 평가 플래그를 가져올 호스트입니다. EU 데이터 센터를 방문하려면 serverZone을 사용하십시오.
  • 기본값: https://flag.lab.amplitude.com
• fetchTimeoutMillis
  • 설명: 변형을 가져오는 데 필요한 시간 초과(밀리초)입니다.
  • 기본값: 10000
• retryFetchOnFailure
  • 설명: 요청이 성공하지 못할 경우 백그라운드에서 변형 가져오기를 재시도할지 여부입니다.
  • 기본값: true
• automaticExposureTracking
  • 설명: true인 경우 variant()를 호출하면 구성된 trackingProvider를 통해 노출 이벤트를 추적합니다. 추적 공급자가 설정되어 있지 않으면 이 구성 옵션은 아무 작업도 수행하지 않습니다.
  • 기본값: true
• fetchOnStart
  • 설명: true이면 항상 시작 시 원격 평가 변형을 가져옵니다. false이면 시작 시 절대로 가져오지 마십시오.
  • 기본값: true
• pollOnStart
  • 설명: 시작 시 로컬 평가 플래그 구성의 업데이트를 주기적으로 확인합니다. 폴링 간격을 flagConfigPollingIntervalMillis로 설정합니다.
  • 기본값: true
• flagConfigPollingIntervalMillis
  • 설명: pollOnStart을 활성화할 때 플래그 구성 폴링 사이의 간격(밀리초)입니다. SDK는 60000 미만의 값을 60000으로 올립니다.
  • 기본값: 300000
• automaticFetchOnAmplitudeIdentityChange
  • 설명: initializeWithAmplitude을 사용하는 경우에만 중요합니다. true인 경우 분석에서 사용자 ID, 장치 ID 또는 사용자 속성이 전체 변경되면 실험 SDK가 변형을 가져오고 해당 캐시를 업데이트하도록 트리거됩니다.
  • 기본값: false
• userProvider
  • 설명: 호출될 때 사용자 객체를 제공하는 인터페이스입니다fetch(). 사용자 공급자로 이동합니다.
  • 기본값: null
• trackingProvider
  • 설명: 이 인터페이스를 구현하고 구성하여 실험 SDK를 통해 노출 이벤트를 자동으로 또는 명시적으로 추적하세요. 노출 추적 공급자로 이동하십시오.
  • 기본값: null
• instanceName
  • 설명: 실험 SDK 인스턴스의 사용자 지정 인스턴스 이름입니다. 이 필드의 값은 대소문자를 구분합니다.
  • 기본값: $default_instance
• initialFlags
  • 설명: 로컬 평가에 사용할 플래그 구성의 초기 집합을 나타내는 JSON 문자열입니다.
  • 기본값: null

통합

Amplitude 애널리틱스 SDK를 사용하여 Amplitude로 이벤트를 추적하는 경우, Amplitude는 초기화 시 연동을 설정할 것을 권장합니다. 통합은 공급자 인터페이스를 구현하여 사용자 ID를 관리하고 노출 이벤트를 추적하기가 더 쉬워짐으로써 보다 간소화된 개발자 환경을 제공합니다.

가져오기

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

Future<void> fetch([ExperimentUser? user, FetchOptions? options])

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

final user = ExperimentUser(
  userId: 'user@company.com',
  deviceId: 'abcdefg',
  userProperties: {'premium': true},
);
await experiment.fetch(user);

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

await experiment.fetch();

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

시작

실험 SDK를 시작하여 서버에서 플래그 구성을 가져오고 사용자를 위한 원격 평가 변형을 가져옵니다. 반환된 Future가 완료되면 SDK가 준비됩니다.

Future<void> start(ExperimentUser? user)

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

SDK 구성에서 fetchOnStart이 설정을 사용하여 start()의 동작을 제어하여 애플리케이션의 성능을 향상시킵니다.

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

await experiment.start(null);

변형

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

Future<Variant> variant(String flagKey, [Variant? fallbackVariant])

사용자가 어떤 버킷에 속했는지 확인할 때는 해당 변형 키를 잘 알려진 문자열과 value비교하십시오.

final variant = await experiment.variant('FLAG_KEY');
if (variant.value == 'on') {
  // Flag is on
} else {
  // Flag is off
}

final variant = await experiment.variant('FLAG_KEY');
if (variant.value == 'on') {
  final payload = variant.payload;
}

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

final variant = await experiment.variant(
  'FLAG_KEY',
  Variant(value: 'control'),
);
if (variant.value == 'control') {
  // Control
} else if (variant.value == 'treatment') {
  // Treatment
}

모두

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

Future<Map<String, Variant>> all()

지우기

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

Future<void> clear()

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

await experiment.clear();

노출:

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

Future<void> exposure(String flagKey)

final variant = await experiment.variant('FLAG_KEY');
// Do other things...
await experiment.exposure('FLAG_KEY');
if (variant.value == 'control') {
  // Control
} else if (variant.value == 'treatment') {
  // Treatment
}

공급자

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

사용자 제공자

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

abstract interface class UserProvider {
  ExperimentUser getUser();
}

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

class CustomUserProvider implements UserProvider {
  @override
  ExperimentUser getUser() {
    // Return the current user from your app's user store
    return ExperimentUser(userId: 'user@company.com');
  }
}
final experiment = await Experiment.initialize(
  'DEPLOYMENT_KEY',
  ExperimentConfig(
    userProvider: CustomUserProvider(),
  ),
);

노출 추적 공급자

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

abstract interface class ExposureTrackingProvider {
  void track(Exposure exposure);
}

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

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

class CustomExposureTracker implements ExposureTrackingProvider {
  @override
  void track(Exposure exposure) {
    // Track the exposure event to your analytics provider
    analytics.track('\$exposure', {
      'flag_key': exposure.flagKey,
      'variant': exposure.variant,
    });
  }
}
final experiment = await Experiment.initialize(
  'DEPLOYMENT_KEY',
  ExperimentConfig(
    trackingProvider: CustomExposureTracker(),
  ),
);

부트스트랩

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

초기 변형

클라이언트를 부트스트랩하려면 initialVariants 구성 옵션에서 플래그와 변형을 설정한 다음 source를 Source.initialVariants로 설정하십시오. 그러면 SDK 클라이언트가 동일한 플래그에 대해 이전에 가져오거나 저장된 전체 변형보다 부트스트랩된 변형을 선호합니다.

final experiment = await Experiment.initialize(
  'DEPLOYMENT_KEY',
  ExperimentConfig(
    initialVariants: {
      'flag-key-1': Variant(value: 'on'),
      'flag-key-2': Variant(value: 'treatment'),
    },
    source: Source.initialVariants,
  ),
);

초기 플래그

로컬 평가를 위해 일련의 플래그 구성으로 클라이언트를 부트스트랩하려면 플래그 구성의 JSON 문자열을 사용하여 initialFlags 구성 옵션을 설정하십시오.

final experiment = await Experiment.initialize(
  'DEPLOYMENT_KEY',
  ExperimentConfig(
    initialFlags: '{"flag-key-1": ...}',
  ),
);