React Native SDK

이 문서는 Amplitude 애널리틱스 React Native SDK에 대한 공식 문서입니다.

호환성 매트릭스

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

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

SDK 설치

프로젝트 디렉토리의 package.json와 동일한 위치에서 yarn add @amplitude/react-native을(를) 실행하십시오.

yarn add @amplitude/react-native

iOS 설치

cd ios && pod install

SDK 초기화

계측하기 전에 Amplitude 프로젝트의 API 키를 사용하여 SDK를 초기화하십시오.

import * as React from 'react';
import { Button } from 'react-native';
import { Amplitude, Identify } from '@amplitude/react-native';
const ampInstance = Amplitude.getInstance();
ampInstance.init(AMPLITUDE_API_KEY);
export function MyApp() {
    return (
    <Button
        title="Log Event"
        onPress=() => ampInstance.logEvent('BUTTON_CLICKED')
    />
    );
}

SDK 구성

Amplitude React Native SDK는 Amplitude Android 유지관리 SDK 및 Amplitude iOS 유지관리 SDK를 기반으로 작동합니다. 다음의 ts/js 구성 옵션은 설정할 수 있습니다. 기타 기본 구성의 경우:

• Android의 경우 Android 구성을 참조하십시오.
• iOS의 경우 iOS 구성을 참조하십시오.

일괄 처리 동작 구성

고성능 환경을 지원하기 위해 SDK는 이벤트를 일괄 처리로 전송합니다. logEvent 메서드는 메모리에 모든 이벤트를 대기열에 넣습니다. SDK는 백그라운드에서 이벤트를 일괄적으로 플러시합니다.setEventUploadThreshold 및 setEventUploadPeriodMillis을 사용하여 일괄 처리 동작을 사용자 지정할 수 있습니다. 기본적으로 serverUrl은 https://api2.amplitude.com/입니다. 이 SDK는 배치 API 엔드포인트를 통한 배치 모드를 지원하지 않습니다.

// Events queued in memory will flush when number of events exceed upload threshold
// Default value is 30
Amplitude.getInstance().setEventUploadThreshold(100);
// Events queue will flush every certain milliseconds based on setting
// Default value is 30 second.
Amplitude.getInstance().setEventUploadPeriodMillis(100000);

EU 데이터 상주

버전 2.6.0부터는 클라이언트를 초기화한 후 Amplitude의 EU 서버로 데이터를 전송하도록 서버 영역을 구성하십시오. SDK는 설정된 서버 영역을 기반으로 데이터를 전송합니다. 서버 영역 구성은 동적 구성도 지원합니다.

이전 버전의 경우 클라이언트를 초기화한 후 serverURL 속성을 구성하십시오.

// For versions starting from 2.6.0
// No need to call setServerUrl for sending data to Amplitude's EU servers
Amplitude.getInstance().setServerZone('EU');
// For earlier versions
Amplitude.getInstance().setServerUrl("https://api.eu.amplitude.com"));

기본 이벤트 전송

이벤트는 사용자가 애플리케이션과 상호 작용하는 방식을 나타냅니다. 예를 들어 ‘버튼 클릭’은 추적하려는 동작일 수 있습니다.

Amplitude.getInstance().logEvent("BUTTON_CLICKED");

속성과 함께 이벤트 전송

이벤트에는 이벤트에 대한 컨텍스트를 제공하는 속성도 포함될 수 있습니다. 예를 들어 '마우스 오버 시간'은 '버튼 클릭'과 관련된 이벤트 속성일 수 있습니다.

Amplitude.getInstance().logEvent("BUTTON_CLICKED", { "Hover Time": "100ms" });

이벤트 플러시

SDK는 일반적으로 이벤트를 버퍼에 저장하고 주기적으로 플러시합니다. 이 동작은 구성이 가능합니다. 이벤트를 수동으로 플러시할 수도 있습니다.

Amplitude.getInstance().uploadEvents();

사용자 속성

사용자 속성은 사용자가 앱 내에서 작업을 수행할 때의 기기 세부 정보, 기본 설정 또는 언어와 같이 해당 시점의 사용자를 이해하는 데 도움이 됩니다.

Amplitude-ReactNative의 Identify 클래스는 이러한 기능을 관리합니다. 사용하기 전에 Identify을(를) 가져오세요.

import { Identify } from "@amplitude/react-native";

사용자 속성 설정

set 는 사용자 속성의 값을 설정합니다. 또한 여러 identify 호출을 함께 연결할 수도 있습니다.

const identify = new Identify();
identify.set("gender", "female").set("age", 20);
Amplitude.getInstance().identify(identify);

setOnce

setOnce 는 사용자 속성의 값을 한 번 설정합니다. setOnce를 사용하는 이후의 호출은 무시됩니다.

const identify1 = new Identify();
identify1.setOnce("sign_up_date", "2015-08-24");
Amplitude.getInstance().identify(identify1);
const identify2 = new Identify();
identify2.setOnce("sign_up_date", "2015-08-24");
Amplitude.getInstance().identify(identify2); // is ignored

추가

add 는 사용자 속성을 숫자 값만큼 증가시킵니다. 사용자 속성에 아직 값이 설정되어 있지 않은 경우 SDK는 값을 0으로 초기화한 후 증분합니다.

const identify = new Identify();
identify.add("karma", 0.123);
Amplitude.getInstance().identify(identify);

여러 사용자 속성 설정

여러 사용자 속성을 한 번에 설정하려면 축약어로 setUserProperties를 사용하십시오. 이 메서드는 Identify.set 및 identify를 감싸는 래퍼입니다.

const userProperties = {
  KEY: "VALUE",
  OTHER_KEY: "OTHER_VALUE",
};
Amplitude.getInstance().setUserProperties(userProperties);

사용자 속성의 배열

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

const colors = ["rose", "gold"];
const numbers = [4, 5];
const identify = new Identify();
identify
  .set("colors", colors)
  .append("ab-tests", "campaign_a")
  .append("existing_list", numbers);
Amplitude.getInstance().identify(identify);

추가

append 는 사용자 속성 배열에 값을 추가합니다. 사용자 속성에 아직 값이 설정되어 있지 않은 경우 SDK는 새 값을 추가하기 전에 빈 목록으로 초기화합니다. 사용자 속성에 기존의 비목록 값이 있는 경우 SDK는 이를 목록으로 변환하고 새 값을 추가합니다.

const array = ["some_string", 56];
const identify = new Identify();
identify.append("ab-tests", "new-user-test");
Amplitude.getInstance().identify(identify);

preInsert

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

const array = ["some_string", 56];
const identify = new Identify();
identify.preInsert("ab-tests", "new-user-test");
Amplitude.getInstance().identify(identify);

postInsert

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

const array = ["some_string", 56];
const identify = new Identify();
identify.postInsert("ab-tests", "new-user-test");
Amplitude.getInstance().identify(identify);

사용자 속성 제거

clearUserProperties 현재 사용자의 모든 사용자 속성을 지웁니다.

Amplitude.getInstance().clearUserProperties();

제거

remove는 사용자 속성에 값이 있을 경우 해당 사용자 속성에서 값 또는 값들을 제거합니다. 해당 항목이 사용자 속성에 존재하지 않는 경우 아무 작업도 수행되지 않습니다.

const array = ["some_string", 56];
const identify = new Identify();
identify.remove("ab-tests", "new-user-test").remove("some_list", array);
Amplitude.getInstance().identify(identify);

설정 해제

unset사용자 속성을 설정 해제하고 제거합니다.

const identify = new Identify();
identify.unset("karma").unset("gender");
Amplitude.getInstance().identify(identify);

매출 추적

Amplitude는 사용자가 창출한 수익을 추적할 수 있습니다. Amplitude는 Amplitude의 이벤트 세분화 및 수익 LTV (Lifetime Value) 차트에서 사용하는 특수 필드를 갖춘 별개의 수익 객체를 통해 수익을 추적합니다.

이를 통해 Amplitude는 플랫폼에 수익 관련 데이터를 자동으로 표시할 수 있습니다. 수익 객체는 다음과 같은 특수 속성과 eventProperties필드를 통해 사용자 정의 속성을 지원합니다.

가격은 음수 값일 수 있으며, 이는 손실된 수익을 추적하는 데 유용합니다.

type RevenueProperties = {
  price: number;
  productId?: string;
  quantity?: number;
  revenueType?: string;
  receipt?: string;
  receiptSignature?: string;
  eventProperties?: PropertiesObject;
};

const userProperties = {
    price: 100;
    productId: "123";
    quantity: 2;
    revenueType: "productRevenue";
    receipt: "11111";
    receiptSignature: "signature";
    eventProperties: {
        "KAY": "VALUE",
      "OTHER_KEY": "OTHER_VALUE"
    };
}
Amplitude.getInstance().logRevenue(userProperties);

그룹 사용자 속성

Group Identify API를 사용하여 특정 그룹의 속성을 설정하거나 업데이트하십시오. 다음 사항을 염두에 두십시오.

• 업데이트는 향후 이벤트에만 영향을 미치며 과거 이벤트를 업데이트하지는 않습니다.
• 최대 5개의 고유 그룹 유형과 총 10개의 그룹을 추적할 수 있습니다.

이 groupIdentify 메서드는 그룹 유형 문자열 매개변수, 그룹 이름 객체 매개변수 및 Identify 객체를 받아들여 그룹에 적용합니다.

const identify = new Identify();
identify.set("gender", "female").set("age", 20);
Amplitude.getInstance().groupIdentify("groupType", "groupValue", identify);

사용자 세션

세션은 사용자가 앱을 포그라운드에 두고 있는 기간입니다. 동일한 세션 내에서 기록된 이벤트는 동일한 session_id를 공유합니다.

SDK는 세션을 자동으로 처리하므로 startSession() 또는 endSession()와 같은 API를 수동으로 호출할 필요가 없습니다. Amplitude는 이벤트를 세션별로 그룹화합니다.

세션은 시작 시간과 종료 시간을 가진 단일 사용자 활동을 나타냅니다. SDK마다 플랫폼 요구 사항에 따라 세션을 다르게 추적합니다.

사용자 세션의 시작 및 종료에 해당하는 세션 시작 및 종료 이벤트를 자동으로 기록할지 여부를 결정할 수 있습니다.

//Enable automatically log start and end session events
Amplitude.getInstance().trackingSessionEvents(true);
//Disable automatically log start and end session events
Amplitude.getInstance().trackingSessionEvents(false);

사용자 지정 사용자 ID 설정

앱에 자체 로그인 시스템이 있고 이를 이용하여 사용자를 추적하려는 경우, 언제든지 setUserId을 호출하십시오.

Amplitude.getInstance().setUserId("test_user_id");

고급옵션 항목

COPPA 제어

IDFA, IDFV, 도시, IP 주소 및 위치 추적에 대한 COPPA(아동 온라인 개인 정보 보호법) 제한을 동시에 활성화 또는 비활성화할 수 있습니다.

13세 미만의 어린이로부터 정보를 요청하는 앱은 COPPA를 준수해야 한다는 점을 기억하십시오.

// Enable COPPA Control
Amplitude.instance().enableCoppaControl();
// Disable COPPA Control
Amplitude.instance().disableCoppaControl();

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

사용자는 이벤트가 발생하지 않고 브라우징 기록이 없음을 의미하는 추적을 완전히 거부하기를 원할 수 있습니다. setOptOut은 특정 사용자의 개인정보 보호 요청을 충족하는 방법을 제공합니다.

//Disables instrumentation
Amplitude.getInstance().setOptOut(true);
//Enables instrumentation
Amplitude.getInstance().setOptOut(false);

동적 구성

React Native SDK를 사용하면 사용자가 앱을 동적 구성을 사용하도록 설정할 수 있습니다. 이 기능은 앱 사용자의 위치를 기반으로 최적의 서버 URL을 자동으로 찾습니다.

• 자체 프록시 서버를 보유하고 있고 setServerUrl API를 사용하는 경우에는 동적 구성을 사용하지 마십시오.
• 중국 본토에 사용자가 있는 경우, Amplitude는 동적 구성을 사용하는 것을 권장합니다.
• 기본적으로 이 기능은 해제되어 있습니다. 이를 사용하려면 명시적으로 활성화해야 합니다.
• 기본적으로 이 기능은 Amplitude의 미국 서버의 서버 URL을 반환합니다. Amplitude의 EU 서버로 데이터를 전송해야 하는 경우, setServerZone을 사용하여 이를 EU 지역으로 설정하세요.

Amplitude.getInstance().setUseDynamicConfig(true);

문제 해결

이전 버전의 React Native를 사용하고 있는데 iOS에 문제가 있나요?

Amplitude는 React Native 0.61 이상의 버전을 지원합니다. React Native 0.71을 사용한 설정 과정은 다음과 같습니다. 자세한 내용은 호환성 매트릭스를 참조하십시오.

1. Swift 설정(Xcode).
   • Xcode에서 [project-name].xcodeproj 파일을 엽니다.
   • 파일 내비게이터에서 프로젝트 이름을 마우스 오른쪽 버튼으로 클릭한 다음, '새 파일'을 선택하고 Swift를 고릅니다. Xcode는 브리징 헤더 파일을 생성하라는 메시지를 표시합니다. 이는 RN 0.61에서 Swift를 지원하기 위해 필요합니다.
   • 이 수정 사항의 소스: https://stackoverflow.com/a/54586937.
2. Podfile 변경.
   • iOS 10 이상을 대상으로 설정해야 합니다.
   • Podfile의 맨 위에 전역적으로 use_modular_headers!을 추가하십시오.
   • :use_modular_headers => false을 사용하여 DoubleConversion, Glog 및 Folly에 대한 모듈식 헤더를 비활성화합니다.