React Native SDK

React Native SDK를 사용하면 이벤트를 Amplitude로 전송할 수 있습니다.

호환성 매트릭스

다음 매트릭스는 다양한 버전의 React Native 및 React Native CLI에 대한 Amplitude React Native SDK 지원을 보여줍니다.

Android Gradle 플러그인 호환성에 대해 자세히 알아보세요.

SDK 설치

Amplitude React Native SDK 사용을 시작하려면 npm을 사용하여 패키지를 프로젝트에 설치하십시오. SDK는 기본적으로 앱 실행 전반에 걸쳐 ID 및 이벤트 큐를 유지하기 위해 @react-native-async-storage/async-storage사용하므로 SDK와 함께 설치하세요. 자체 스토리지 백엔드를 사용하기를 원한다면 AsyncStorage 옵트아웃을 참조하십시오.

npm install @amplitude/analytics-react-native
npm install @react-native-async-storage/async-storage

네이티브 모듈을 설치하여 iOS에서 SDK를 실행하십시오.

cd ios
pod install

SDK 초기화

전체 계측 작업을 수행하기 전에 SDK를 초기화하십시오. Amplitude 프로젝트에 대한 API 키는 필수입니다. 이 호출에서 사용자 ID 및 구성 객체를 선택적으로 전달할 수 있습니다. SDK를 초기화한 후에는 애플리케이션의 어디에서나 사용할 수 있습니다.

import { init } from "@amplitude/analytics-react-native";
// Option 1, initialize with API_KEY only
init(API_KEY);
// Option 2, initialize including user ID if it's already known
init(API_KEY, "user@amplitude.com");
// Option 3, initialize including configuration
init(API_KEY, "user@amplitude.com", {
  disableCookies: true, // Disables the use of browser cookies
});

SDK 구성

일괄 처리 동작 구성

고성능 환경을 지원하기 위해 SDK는 이벤트를 일괄 처리로 전송합니다. track 메서드는 메모리에 모든 이벤트를 대기열에 넣습니다. SDK는 백그라운드에서 이벤트를 일괄적으로 플러시합니다.flushQueueSize 및 flushIntervalMillis을 사용하여 일괄 처리 동작을 사용자 정의할 수 있습니다. 기본적으로 serverUrl은 https://api2.amplitude.com/2/httpapi입니다. 한 번에 대량의 데이터를 전송하려면 useBatch를 true로 설정하여 setServerUrl을 배치 이벤트 업로드 API인 https://api2.amplitude.com/batch로 설정하십시오. 일반 모드와 배치 모드 모두 동일한 이벤트 업로드 임계값과 플러시 시간 간격을 사용합니다.

import * as amplitude from "@amplitude/analytics-react-native";
amplitude.init(API_KEY, OPTIONAL_USER_ID, {
  // Events queued in memory will flush when number of events exceed upload threshold
  // Default value is 30
  flushQueueSize: 50,
  // Events queue will flush every certain milliseconds based on setting
  // Default value is 10000 milliseconds
  flushIntervalMillis: 20000,
});

오프라인 모드

1.6.0 버전부터, React Native SDK는 오프라인 모드를 지원합니다. SDK는 기기의 네트워크 연결이 끊어지는 경우를 감지하고 이벤트를 삭제하는 대신 대기열에 넣습니다. 기기가 오프라인 상태인 동안에도 SDK는 추적된 이벤트를 스토리지에 유지하고 업로드 시도를 중지합니다. 기기가 다시 연결되면 SDK는 대기열에 저장된 이벤트를 Amplitude로 플러시합니다. 오프라인 모드는 기본적으로 설정되어 있으므로 구성할 필요가 없습니다.

SDK는 iOS 및 ConnectivityManagerAndroid의 기본 모듈을 통해 연결을 감지합니다. NWPathMonitor웹(react-native-web)에서 SDK는 브라우저의 navigator.onLine 상태와 online 이벤트를 offline 사용합니다.

SDK는 디바이스가 오프라인 상태인 동안 이벤트를 스토리지에 지속적으로 저장하므로 구성된 값은 오프라인 대기열의 storageProvider크기를 제한합니다. SDK가 대기열에 저장한 이벤트를 어디에 저장하는지 변경하려면 AsyncStorage 옵트아웃을 참조하십시오.

네이티브 모듈 설정

연결 감지는 SDK의 네이티브 모듈에 의존합니다.

• iOS: pod install를 실행할 때 네이티브 모듈이 자동으로 연결됩니다. SDK 설치를 참조하십시오. 지원되는 최소 iOS 배포 타겟은 13.0입니다.
• Android: SDK는 해당 매니페스트에 권한을 선언하며, 이 권한은 앱의 매니페스트에 자동으로 병합됩니다. ACCESS_NETWORK_STATE전체 수동 변경을 수행할 필요가 없습니다.

오프라인 모드 비활성화

자동 연결 감지를 해제하려면 SDK를 초기화할 때 OfflineDisabled을 offline으로 설정하십시오.

import * as amplitude from "@amplitude/analytics-react-native";
amplitude.init(API_KEY, OPTIONAL_USER_ID, {
  offline: amplitude.Types.OfflineDisabled,
});

오프라인 모드를 비활성화하면 SDK는 flushIntervalMillis 및 flushQueueSize 만을 기준으로 이벤트를 플러시합니다. 자체 오프라인 로직을 구현하려면 그림과 같이 오프라인 모드를 비활성화한 다음 자체 네트워크 감지에 따라 config.offline 을(를) 전환하십시오.

EU 데이터 상주

Amplitude의 EU 서버로 데이터를 전송하기 위해 클라이언트를 초기화할 때 서버 영역을 구성할 수 있습니다. SDK는 사용자가 서버 영역을 설정한 경우 이를 기반으로 데이터를 전송합니다.

amplitude.init(API_KEY, OPTIONAL_USER_ID, {
  serverZone: "EU",
});

디버깅

개발자 콘솔에 인쇄되는 로그 수준을 제어할 수 있습니다.

• 'None': 모든 로그 메시지를 표시하지 않습니다.
• '오류': 오류 메시지만 표시합니다.
• '경고': 오류 메시지와 경고를 표시합니다. logLevel을 명시적으로 지정하지 않은 경우 이 값이 기본값입니다.
• 'Verbose': 정보가 풍부한 메시지를 표시합니다.
• '디버그': 모든 SDK 공용 메소드 호출에 대한 함수 컨텍스트 정보를 비롯하여 디버깅에 도움이 될 수 있는 오류 메시지, 경고 및 유용한 메시지를 표시합니다. 이 로깅 모드는 개발 단계에서만 사용하십시오.

logLevel를 원하는 수준으로 구성하여 로그 수준을 설정합니다.

amplitude.init(AMPLITUDE_API_KEY, OPTIONAL_USER_ID, {
  logLevel: amplitude.Types.LogLevel.Warn,
});

기본 로거는 개발자 콘솔에 로그를 출력합니다. 사용자 정의를 위해 Logger인터페이스를 기반으로 자체 로거 구현을 제공할 수 있습니다. 예를 들어 프로덕션 환경의 SDK에서 오류 메시지를 수집할 수 있습니다.

loggerProvider를 자체 구현으로 구성하여 로거를 설정하십시오.

amplitude.init(AMPLITUDE_API_KEY, OPTIONAL_USER_ID, {
  loggerProvider: new MyLogger(),
});

디버그 모드

logLevel를 "디버그"로 설정하여 디버그 모드를 활성화하십시오. 예를 들면 다음과 같습니다.

amplitude.init(AMPLITUDE_API_KEY, OPTIONAL_USER_ID, {
  logLevel: amplitude.Types.LogLevel.Debug,
});

기본 로거는 사용자가 전체 SDK 공용 메소드를 호출할 때 다음과 같은 추가 함수 컨텍스트 정보를 개발자 콘솔에 출력합니다.

• 'type': 이 컨텍스트의 범주(예: "공용 메소드 호출").
• 'name': 호출된 함수의 이름입니다(예: "track").
• 'args': 호출된 함수의 인수입니다.
• 'stacktrace': 호출된 함수의 스택트레이스입니다.
• 'time': 함수 호출의 시작 및 종료 타임스탬프입니다.
• 'states': 함수 호출 전후의 유용한 내부 상태 스냅샷입니다.

이벤트 추적

이벤트는 사용자가 애플리케이션과 상호 작용하는 방식을 나타냅니다. 예를 들어 '버튼 클릭됨'은 기록해야 할 동작일 수 있습니다.

import { track } from "@amplitude/analytics-react-native";
// Track a basic event
track("Button Clicked");
// Track events with optional properties
const eventProperties = {
  buttonColor: "primary",
};
track("Button Clicked", eventProperties);

여러 프로젝트에 대한 이벤트 추적

이벤트를 여러 Amplitude 프로젝트에 기록하려면 각 Amplitude 프로젝트에 대해 별도의 인스턴스를 생성하십시오. 그런 다음 Amplitude를 호출하려는 모든 위치에 인스턴스 변수를 전달하십시오. 각 인스턴스는 독립적인 apiKeys, userIds, deviceIds및 설정을 허용합니다.

import * as amplitude from "@amplitude/analytics-react-native";
const defaultInstance = amplitude.createInstance();
defaultInstance.init(API_KEY_DEFAULT);
const envInstance = amplitude.createInstance();
envInstance.init(API_KEY_ENV, {
  instanceName: "env",
});

사용자 속성

사용자 속성은 사용자가 앱 첫 사용 후 어떤 작업을 수행했을 때의 사용자를 이해하는 데 도움이 됩니다(예: 사용자의 기기 세부 정보, 환경 설정, 언어).

Identify를 사용하면 이벤트를 전송하지 않고도 특정 사용자의 사용자 속성을 설정할 수 있습니다. SDK는 개별 사용자 속성에 대해 set, setOnce, unset, add, append, prepend, preInsert, postInsert, remove 및 clearAll 작업을 지원합니다. 제공된 Identify 인터페이스를 통해 작업을 선언합니다. 단일 Identify 객체에서 여러 작업을 함께 연결할 수 있습니다. 그런 다음 Identify 오브젝트를 Amplitude 클라이언트에 전달하여 서버로 전송합니다.

Identify

Identify 객체는 사용자 속성 설정을 제어할 수 있는 기능을 제공합니다. 먼저 Identify 객체를 인스턴스화합니다. 그런 다음, 이에 대해 Identify 메서드를 호출합니다. 마지막으로, 클라이언트는 Identify 객체를 사용하여 호출을 수행합니다.

import { identify, Identify } from "@amplitude/analytics-react-native";
const identifyObj = new Identify();
identify(identifyObj);

Identify.set

이 메서드는 사용자 속성의 값을 설정합니다. 예를 들어 사용자의 역할 속성을 설정할 수 있습니다.

import { Identify, identify } from "@amplitude/analytics-react-native";
const identifyObj = new Identify();
identifyObj.set("location", "LAX");
identify(identifyObj);

Identify.setOnce

이 메서드는 사용자 속성의 값을 한 번만 설정합니다. SDK는 setOnce()를 사용하여 후속 호출을 무시합니다. 예를 들어 사용자의 초기 로그인 방법을 설정할 수 있습니다. SDK는 초기 값만 추적하므로 setOnce()는 후속 호출을 무시합니다.

import { Identify, identify } from "@amplitude/analytics-react-native";
const identifyObj = new Identify();
identifyObj.setOnce("initial-location", "SFO");
identify(identifyObj);

Identify.add

이 메서드는 사용자 속성을 일부 숫자 값만큼 증가시킵니다. 사용자 속성에 아직 값이 설정되어 있지 않은 경우, SDK는 IT를 0으로 초기화한 후 증분합니다. 예를 들어 사용자의 여행 수행 횟수를 추적할 수 있습니다.

import { Identify, identify } from "@amplitude/analytics-react-native";
const identifyObj = new Identify();
identifyObj.add("travel-count", 1);
identify(identifyObj);

사용자 속성의 배열

배열을 사용자 속성으로 사용할 수 있습니다. 배열을 직접 설정하거나 prepend, append, preInsert, 및 postInsert를 사용하여 배열을 생성할 수 있습니다.

Identify.prepend

이 메서드는 사용자 속성 배열 앞에 값을 추가합니다. 사용자 속성에 아직 값이 설정되어 있지 않은 경우, SDK는 새 값을 앞에 추가하기 전에 빈 목록으로 초기화합니다.

import { Identify, identify } from "@amplitude/analytics-react-native";
const identifyObj = new Identify();
identifyObj.prepend("visited-locations", "LAX");
identify(identifyObj);

Identify.append

이 메서드는 사용자 속성 배열에 하나 이상의 값을 추가합니다. 사용자 속성에 아직 값이 설정되어 있지 않은 경우 SDK는 새 값을 추가하기 전에 해당 속성을 빈 목록으로 초기화합니다.

import { Identify, identify } from "@amplitude/analytics-react-native";
const identifyObj = new Identify();
identifyObj.append("visited-locations", "SFO");
identify(identifyObj);

Identify.preInsert

이 메서드는 사용자 속성에 값이 아직 존재하지 않는 경우 해당 값을 사용자 속성에 미리 삽입합니다. 사전 삽입은 지정된 목록의 시작 부분에 값을 삽입하는 것을 의미합니다. 사용자 속성에 아직 값이 설정되어 있지 않은 경우, SDK는 새 값을 미리 삽입하기 전에 이를 빈 목록으로 초기화합니다. 사용자 속성에 기존 값이 있으면 SDK는 아무 작업도 수행하지 않습니다.

import { Identify, identify } from "@amplitude/analytics-react-native";
const identifyObj = new Identify();
identifyObj.preInsert("unique-locations", "LAX");
identify(identifyObj);

Identify.postInsert

이 메서드는 사용자 속성에 값이 아직 존재하지 않는 경우 해당 값을 사용자 속성에 사후 삽입합니다. 사후 삽입은 주어진 목록의 끝에 값을 삽입하는 것을 의미합니다. 사용자 속성에 아직 값이 설정되어 있지 않은 경우, SDK는 새 값을 사후 추가하기 전에 빈 목록으로 초기화합니다. 사용자 속성에 기존 값이 있으면 SDK는 아무 작업도 수행하지 않습니다.

import { Identify, identify } from "@amplitude/analytics-react-native";
const identifyObj = new Identify();
identifyObj.postInsert("unique-locations", "SFO");
identify(identifyObj);

Identify.remove

이 메서드는 사용자 속성에 값이 있는 경우 사용자 속성에서 해당 값을 제거합니다. 제거는 주어진 목록에서 기존 값을 제거한다는 의미입니다. 해당 항목이 사용자 속성에 존재하지 않는 경우 SDK는 작업을 수행하지 않습니다.

import { Identify, identify } from "@amplitude/analytics-react-native";
const identifyObj = new Identify();
identifyObj.remove("unique-locations", "JFK");
identify(identifyObj);

Identify.clearAll

이 메서드는 사용자로부터 모든 사용자 속성을 제거합니다. clearAll는 되돌릴 수 없는 작업이므로 주의해서 사용하십시오.

import { Identify, identify } from "@amplitude/analytics-react-native";
const identifyObj = new Identify();
identifyObj.clearAll();
identify(identifyObj);

사용자 그룹

Amplitude는 사용자를 그룹에 할당하고 해당 그룹에 대해 고유 사용자별 수행 회수가와 같은 쿼리를 수행하는 것을 지원합니다. 그룹 구성원 중 적어도 한 명이 특정 이벤트를 수행한 경우 해당 그룹도 수행 회수가에 포함됩니다.

예를 들어 'orgId'를 사용하여 사용자가 속한 조직을 기준으로 사용자를 그룹화하려는 경우가 있습니다. Joe는 'orgId' '10'에 있고 Sue는 'orgId' '15'에 있습니다. Sue와 Joe는 둘 다 특정 이벤트를 수행합니다. 이벤트 세분화 차트에서 해당 조직을 쿼리할 수 있습니다.

그룹을 설정할 때 groupType 및 groupName를 정의하십시오. 이전 예제에서 'orgId'는 groupType이고 '10'과 '15'는 groupName에 대한 값입니다. groupType의 또 다른 예로는 'tennis' 및 'baseball'과 같은 groupName 값을 가진 'sport'가 있을 수 있습니다.

또한 그룹을 설정하면 groupType:groupName를 사용자 속성으로 설정하고 해당 사용자의 groupType에 대해 설정된 기존 groupName값과 해당 사용자 속성 값을 덮어씁니다. groupType은 문자열이며 사용자가 여러 그룹에 속해 있음을 나타내는 문자열 또는 문자열 배열일 groupName수 있습니다.

import { setGroup } from "@amplitude/analytics-react-native";
// set group with single group name
setGroup("orgId", "15");

import { setGroup } from "@amplitude/analytics-react-native";
// set group with multiple group names
setGroup("sport", ["soccer", "tennis"]);

groups을 포함한 Event 객체를 track에 전달하여 이벤트 수준 그룹을 설정할 수도 있습니다. 이벤트 수준 그룹의 경우 그룹 지정은 사용자가 기록하는 특정 이벤트에만 적용되며 setGroup를 사용하여 명시적으로 설정하지 않는 한 사용자에게 지속되지 않습니다.

import { track } from "@amplitude/analytics-react-native";
track({
  event_type: "event type",
  event_properties: { eventPropertyKey: "event property value" },
  groups: { orgId: "15" },
});

그룹 속성

Group Identify API를 사용하여 특정 그룹의 속성을 설정하거나 업데이트하십시오. 이러한 업데이트는 앞으로 진행되는 이벤트에만 영향을 줍니다.

이 groupIdentify() 메서드는 그룹 유형 및 그룹 이름 문자열 매개변수와 SDK가 그룹에 적용하는 Identify 객체를 허용합니다.

import { Identify, groupIdentify } from "@amplitude/analytics-react-native";
const groupType = "plan";
const groupName = "enterprise";
const event = new Identify();
event.set("key1", "value1");
groupIdentify(groupType, groupName, identify);

매출 추적

사용자의 수익을 추적하는 선호되는 방법은 제공된 Revenue 인터페이스와 함께 revenue()을 사용하는 것입니다. 수익 인스턴스는 각 수익 거래를 저장하며, Amplitude가 이벤트 세분화 및 수익 LTV (Lifetime Value) 차트에서 사용하는 몇 가지 특별한 수익 속성(예: "revenueType", "productIdentifier" 등)을 정의할 수 있도록 해줍니다. 그런 다음 SDK는 이러한 Revenue 인스턴스 객체를 revenue()에 전달하여 Amplitude에 수익 이벤트로 전송합니다. 이를 통해 Amplitude는 플랫폼의 수익과 관련된 데이터를 자동으로 표시할 수 있습니다. 이 기능을 사용하여 앱 내 구매와 앱 내 이외의 구매를 모두 추적할 수 있습니다.

사용자의 수익을 추적하려면 사용자가 수익을 창출할 때마다 수익을 호출하십시오. 예를 들어 사용자가 한 제품의 3개를 3.99달러에 구매한다고 가정합니다.

import { Revenue, revenue } from "@amplitude/analytics-react-native";
const event = new Revenue()
  .setProductId("com.company.productId")
  .setPrice(3.99)
  .setQuantity(3);
revenue(event);

수익 인터페이스

이벤트 버퍼 플러시

이 flush 메서드는 클라이언트가 버퍼링된 이벤트를 전송하도록 트리거합니다.

import { flush } from "@amplitude/analytics-react-native";
flush();

기본적으로 SDK는 일정한 간격으로 자동으로 flush호출합니다. 이벤트를 모두 플러시하려면 선택적 Promise 인터페이스를 사용하여 비동기 흐름을 제어할 수 있습니다. 예를 들면 다음과 같습니다.

await init(AMPLITUDE_API_KEY).promise;
track("Button Clicked");
await flush().promise;

사용자 지정 사용자 ID

앱에 사용자를 추적하려는 자체 로그인 시스템이 있는 경우 언제든지 setUserId를 호출할 수 있습니다.

타입스크립트

import { setUserId } from "@amplitude/analytics-react-native";
setUserId("user@amplitude.com");

또한 사용자 ID를 init 호출의 인수로 할당할 수도 있습니다.

import { init } from "@amplitude/analytics-react-native";
init(API_KEY, "user@amplitude.com");

사용자 지정 세션 ID

setSessionId를 사용하여 새 세션 ID를 할당할 수 있습니다. 사용자 지정 세션 ID를 설정할 때는 값이 에포크 이후 밀리초 단위인지 확인하십시오(Unix 타임스탬프).

타입스크립트

import { setSessionId } from "@amplitude/analytics-react-native";
setSessionId(Date.now());

사용자 지정 장치 ID

deviceId를 사용하여 새 장치 ID를 할당할 수 있습니다. 사용자 지정 장치 ID를 설정할 때는 값이 충분히 고유한지 확인하십시오. Amplitude는 UUID를 권장합니다.

import { setDeviceId } from "@amplitude/analytics-react-native";
const { uuid } = require("uuidv4");
setDeviceId(uuid());

사용자가 로그아웃할 때 재설정

reset는 사용자가 로그아웃한 후 익명화하는 바로 가기입니다. 방법은 다음과 같습니다.

• userId을 undefined로 설정합니다.
• 새 UUID 값으로 deviceId설정합니다.

정의되지 않은 userId상태이고 완전히 새로운 deviceId상태인 경우 현재 사용자는 대시보드에 완전히 새로운 사용자로 표시됩니다.

import { reset } from "@amplitude/analytics-react-native";
reset();

사용자를 추적에서 해제합니다

true을 setOptOut로 설정하여 지정된 사용자에 대한 로깅을 해제할 수 있습니다.

import { setOptOut } from "@amplitude/analytics-react-native";
setOptOut(true);

SDK는 setOptOut가 활성화되어 있는 동안 전체 이벤트도 서버에 저장하거나 전송하지 않으며, 이 설정은 페이지가 로드될 때에도 지속됩니다.

false로 설정하여 setOptOut로깅을 다시 활성화합니다.

import { setOptOut } from "@amplitude/analytics-react-native";
setOptOut(false);

추적 옵션

기본적으로 SDK는 이러한 속성을 자동으로 추적합니다. SDK를 초기화할 때 trackingOptions 라는 구성을 전달하고 해당 옵션을 false로 설정하여 이 동작을 재정의할 수 있습니다.

amplitude.init(API_KEY, OPTIONAL_USER_ID, {
  trackingOptions: {
    adid: false,
    appSetId: false,
    carrier: false,
    deviceManufacturer: false,
    deviceModel: false,
    ipAddress: false,
    idfv: false,
    language: false,
    osName: false,
    osVersion: false,
    platform: false,
  },
});

콜백

모든 비동기 API는 선택적으로 Promise 인터페이스를 통해 대기할 수 있습니다. Promise 인터페이스는 콜백 인터페이스로도 사용됩니다.

import { track } from "@amplitude/analytics-react-native";
// Using async/await
const results = await track("Button Clicked").promise;
result.event; // {...} (The final event object sent to Amplitude)
result.code; // 200 (The HTTP response status code of the request.
result.message; // "Event tracked successfully" (The response message)
// Using promises
track("Button Clicked").promise.then((result) => {
  result.event; // {...} (The final event object sent to Amplitude)
  result.code; // 200 (The HTTP response status code of the request.
  result.message; // "Event tracked successfully" (The response message)
});

플러그인

플러그인을 사용하면 이벤트 속성을 수정하거나(보강 유형), 타사 API로 전송(목적지 유형)하는 등의 방법으로 Amplitude SDK의 동작을 확장할 수 있습니다. 플러그인은 setup() 및 execute() 메서드를 가진 객체입니다.

Segment와의 세션 리플레이 연동에 대해서는 Session Replay React Native Segment Integration 가이드를 참조하세요.

추가

add 메소드는 Amplitude에 플러그인을 추가합니다. 플러그인은 이벤트를 처리하고 전송하는 데 도움이 될 수 있습니다.

import { add } from "@amplitude/analytics-react-native";
add(new Plugin());

제거

remove 메서드는 클라이언트 인스턴스에 지정된 플러그인 이름이 있는 경우 해당 이름을 제거합니다.

import { remove } from "@amplitude/analytics-react-native";
remove(plugin.name);

플러그인 설정

이 메서드는 플러그인을 사용할 준비를 위한 논리를 포함하고 있으며 config를 매개변수로 사용합니다. 예상 반환 값은 undefined입니다. 이 메서드의 일반적인 용도는 config에서 구성을 복사하거나 플러그인 의존성을 인스턴스화하는 것입니다. SDK는 client.add()를 통해 클라이언트에 플러그인을 등록할 때 이 메서드를 호출합니다.

Plugin.execute

이 메서드에는 이벤트를 처리하기 위한 논리가 포함되어 있으며 이벤트를 매개변수로 사용합니다. 보강 유형 플러그인으로서 예상 반환 값은 수정되거나 보강된 이벤트입니다. 목적지 유형 플러그인으로서 예상되는 반환 값은 event(BaseEvent), code(number), message(string) 키가 있는 맵입니다. SDK는 Identify, GroupIdentify 및 Revenue 이벤트를 비롯하여 클라이언트 인터페이스를 통해 계측하는 각 이벤트에 대해 이 메서드를 호출합니다.

보강 유형 플러그인 예제

다음은 100부터 시작하는 이벤트의 event_id속성에 증분 정수를 추가하여 계측된 각 이벤트를 수정하는 플러그인의 예입니다.

import { init, add } from "@amplitude/analytics-react-native";
import {
  ReactNativeConfig,
  EnrichmentPlugin,
  Event,
  PluginType,
} from "@amplitude/analytics-types";
export class AddEventIdPlugin implements EnrichmentPlugin {
  name = "add-event-id";
  type = PluginType.ENRICHMENT as const;
  currentId = 100;
  config?: ReactNativeConfig;
  /**
   * setup() is called on plugin installation
   * example: client.add(new AddEventIdPlugin());
   */
  async setup(config: ReactNativeConfig): Promise<undefined> {
    this.config = config;
    return;
  }
  /**
   * execute() is called on each event instrumented
   * example: client.track('New Event');
   */
  async execute(event: Event): Promise<Event> {
    event.event_id = this.currentId++;
    return event;
  }
}
init("API_KEY");
add(new AddEventIdPlugin());

목적지 유형 플러그인 예제

다음은 사용자가 선호하는 HTTP 클라이언트를 사용하여 각 계측된 이벤트를 대상 서버 URL로 전송하는 플러그인의 예입니다.

import { init, add } from "@amplitude/analytics-react-native";
import {
  ReactNativeConfig,
  DestinationPlugin,
  Event,
  PluginType,
  Result,
} from "@amplitude/analytics-types";
export class MyDestinationPlugin implements DestinationPlugin {
  name = "my-destination-plugin";
  type = PluginType.DESTINATION as const;
  serverUrl: string;
  config?: ReactNativeConfig;
  constructor(serverUrl: string) {
    this.serverUrl = serverUrl;
  }
  /**
   * setup() is called on plugin installation
   * example: client.add(new MyDestinationPlugin());
   */
  async setup(config: ReactNativeConfig): Promise<undefined> {
    this.config = config;
    return;
  }
  /**
   * execute() is called on each event instrumented
   * example: client.track('New Event');
   */
  async execute(event: Event): Promise<Result> {
    const payload = { key: "secret", data: event };
    const response = await fetch(this.serverUrl, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Accept: "*/*",
      },
      body: JSON.stringify(payload),
    });
    return {
      code: response.status,
      event: event,
      message: response.statusText,
    };
  }
}
init("API_KEY");
add(new MyDestinationPlugin("https://custom.domain.com"));

고급옵션 항목

AsyncStorage 옵트아웃

React Native SDK는 앱 실행 전반에 걸쳐 ID 및 이벤트 큐를 유지하기 위해 @react-native-async-storage/async-storage를 사용합니다. 자체 스토리지 백엔드를 사용하려는 경우(예: react-native-mmkv암호화된 저장소 또는 SQLite), 자체 스토리지를 제공하고 네이티브 빌드에서 AsyncStorage를 제외할 수 있습니다.

SDK는 두 개의 별도 스토리지 슬롯을 사용합니다.

• storageProvider 이벤트 큐(Amplitude로 플러시되기를 기다리는 이벤트)에 사용됩니다.
• cookieStorage ID 및 세션 상태(장치 ID, 사용자 ID, 세션 ID)에 대한 정보.

완전히 옵트아웃하려면 두 가지 항목을 모두 재정의하세요. 만 오버라이드하는 storageProvider경우에도 SDK는 여전히 기본 체인을 통해 ID를 읽고 쓰려고 시도하며, 이는 네이티브의 AsyncStorage로 폴백됩니다. 또한 AsyncStorage를 제거한 경우 ID는 인메모리로 저하되고 앱을 실행할 때마다 재설정됩니다.

초기화 시 두 스토리지 슬롯 모두 재정의하십시오

Storage인터페이스를 구현하고 두 슬롯을 모두 전달하십시오. init의 서명은 (apiKey, userId, options)— undefined 또는 userId에 대한 원하는 사용자 ID를 전달하여 오버라이드가 옵션 슬롯에 적용되도록 하십시오.

import { init } from "@amplitude/analytics-react-native";
init(API_KEY, undefined, {
  storageProvider: myEventQueueStorage,
  cookieStorage: myIdentityStorage,
});

네이티브 자동 링크에서 AsyncStorage 제외

두 기본 플랫폼 모두 null로 설정된 상태에서 패키지를 react-native.config.js에 추가하십시오.

module.exports = {
  dependencies: {
    "@react-native-async-storage/async-storage": {
      platforms: { ios: null, android: null },
    },
  },
};

AsyncStorage는 더 이상 iOS 또는 Android 바이너리에 연결되지 않습니다. JS 패키지는 node_modules 에 유지되므로 require() 가 여전히 해결되지만, 두 스토리지 슬롯을 모두 재정의했기 때문에 SDK는 전체 AsyncStorage 메서드를 호출하지 않습니다.

사용자 지정 HTTP 클라이언트

사용자 정의를 위해 transportProvider 인터페이스의 구현을 Transport 구성 옵션에 제공할 수 있습니다. 예를 들어 사용자 정의된 HTTP 요청 헤더를 사용하여 프록시 서버에 요청을 보낼 수 있습니다.

import { Transport } from "@amplitude/analytics-types";
class MyTransport implements Transport {
  async send(serverUrl: string, payload: Payload): Promise<Response | null> {
    // check example: https://github.com/amplitude/Amplitude-TypeScript/blob/main/packages/analytics-client-common/src/transports/fetch.ts
  }
}
amplitude.init(API_KEY, OPTIONAL_USER_ID, {
  transportProvider: new MyTransport(),
});

위치

Amplitude 수집 서버는 다음 순서로 이벤트 위치를 확인합니다.

1. 사용자 제공 city, country, region.
2. location_lat및 location_lng에서 해결되었습니다.
3. ip에서 해결되었습니다.

기본적으로 서버는 ip에서 위치를 확인합니다. 보다 세부적인 위치를 제공하려면 city, country, region를 개별적으로 설정하거나, city및 country를 설정하면 서버가 이를 location_lat, location_lng, 및 region로 확인합니다. Amplitude는 모든 고객이 필요로 하지 않는 추가 권한 관리를 방지하기 위해 SDK에서 정확한 위치를 설정하지 않습니다.

세밀한 위치를 설정하려면 enrichment 플러그인을 사용할 수 있습니다. 다음은 location_lat및 location_lng을 설정하는 방법에 대한 예입니다.

TrackingOptions에서 ipAddress: false로 IP 추적을 비활성화하면 백엔드가 위치를 확인할 수 없습니다. 이 경우 이전 예제와 같은 플러그인을 만들어 전체 관련 위치 정보를 직접 설정할 수 있습니다.

이동통신사

통신사 지원은 Android에서 작동하지만 Apple은 iOS 16에서 이를 지원하지 않았습니다. 이전 버전의 iOS에서는 SDK가 CTCarrier및 serviceSubscriberCellularProviders을 사용하여 통신사 정보를 가져옵니다. 이러한 기능은 대체 기능이 없으며 더 이상 사용되지 않습니다.

광고 식별자

플랫폼마다 광고 식별자가 다릅니다. 사용자 개인정보 보호 문제로 인해 Amplitude는 이러한 식별자를 자동으로 수집하지 않습니다. 다음 지침을 사용하여 이를 활성화할 수 있습니다. 플랫폼 공급업체는 더 이상 일부 식별자의 사용을 권장하지 않습니다. 이 기능을 사용하도록 결정하기 전에 다음 참고 사항을 읽으십시오.

Android

앱 세트 ID

앱 세트 ID는 기기에 설치된 각 앱의 고유 식별자입니다. 사용자가 앱을 제거할 때 또는 13개월 동안 앱을 열지 않은 후 앱 세트 ID를 수동으로 재설정합니다. Google은 이를 강력한 분석을 거부하려는 사용자를 위해 광고 ID에 대한 개인정보 보호 친화적 대안으로 설계했습니다.

앱 세트 ID를 사용하려면 다음 단계를 수행하십시오.

1. 앱의 Android 프로젝트에 종속성으로 play-services-appset추가하십시오.

   bash

   복사

   dependencies {
       implementation 'com.google.android.gms:play-services-appset:16.0.2'
   }
   

2. trackingOptions.appSetId를 활성화합니다.

   ts

   복사

   amplitude.init(API_KEY, OPTIONAL_USER_ID, {
     trackingOptions: {
       appSetId: true,
     },
   });
   

Android 광고 ID

Android 광고 ID는 각 기기의 고유 식별자입니다. 사용자가 개인화된 광고를 거부할 때 Android 광고 ID를 수동으로 재설정합니다.

Android 광고 ID를 사용하려면 다음 단계를 따르십시오.

1. 앱의 Android 프로젝트에 종속성으로 play-services-ads-identifier추가하십시오. 최신 Android SDK 문서에서는 보다 자세한 설정을 설명합니다.

   bash

   복사

   dependencies {
     implementation 'com.google.android.gms:play-services-ads-identifier:18.0.1'
   }
   

Android 광고 ID는 기본적으로 활성화되어 있습니다. 비활성화하려면 trackingOptions.adId로 설정하십시오false.

amplitude.init(API_KEY, OPTIONAL_USER_ID, {
  trackingOptions: {
    adId: false,
  },
});

iOS

IDFV

IDFV는 앱 인스턴스의 고유 식별자입니다. 사용자가 앱을 다시 설치할 때 시스템은 IDFV를 재설정합니다.

iOS 장치에서 IDFV를 활성화하려면 trackingOptions.idfv로 설정하십시오true.

amplitude.init(API_KEY, OPTIONAL_USER_ID, {
  trackingOptions: {
    idfv: true,
  },
});

IDFA

IDFA는 디바이스의 고유 식별자입니다. 사용자가 개인화된 광고를 거부할 때 시스템은 IDFA를 재설정합니다.

React Native SDK는 AdSupport.framework를 앱에 추가해야 하기 때문에 IDFA에 직접 액세스하지 않습니다. 대신, 보강 플러그인을 사용하여 IDFA를 직접 설정할 수 있습니다.

다음은 타사 라이브러리를 사용하여 IDFA를 설정하는 플러그인 예제입니다.

무선 업데이트(OTA)

OTA 업데이트를 지원하는 Expo와 같은 플랫폼을 사용하는 경우 SDK에 네이티브 코드와 JS 코드가 모두 포함되어 있다는 점에 유의하십시오. OTA 업데이트를 사용할 때는 네이티브 코드도 업데이트해야 합니다. 자세한 내용은 Expo의 배포 및 런타임 버전에 관한 문서를 참조하십시오.

다음 표에는 네이티브 코드가 변경된 SDK 버전이 나와 있습니다.