가이드 및 설문조사 React Native SDK

Amplitude의 가이드 및 설문조사 SDK를 사용하면 웹사이트 또는 애플리케이션에 가이드 및 설문조사를 배포할 수 있습니다.

설치 및 확인

다음 단계에 따라 SDK를 설치하고, 앱을 Amplitude 프로젝트에 연결하며, 가이드 및 설문조사가 앱에 도달하는지 확인하십시오.

요구 사항

가이드 및 설문조사 React Native SDK의 요구 사항은 다음과 같습니다.

• "새로운" React Native 아키텍처.
• React Native 0.79.2 이상.
• Android Gradle 8.7.2 이상.
• Gradle 8 이상.
• iOS 15 이상.
• Swift 5.9 이상.

설치

SDK 설치

가이드 및 설문조사 React Native SDK를 npm 또는 Yarn과 함께 패키지로 설치하십시오.

npm install @amplitude/plugin-engagement-react-native
npm install @react-native-async-storage/async-storage

ios 디렉토리에서 pod install를 실행합니다.

cd ios
bundle exec pod install

SDK 초기화

//index.js
import { Linking } from "react-native";
import { init, add } from "@amplitude/analytics-react-native";
import {
  getPlugin,
  handleURL,
} from "@amplitude/plugin-engagement-react-native";
init("<<< YOUR API KEY HERE >>>");
add(getPlugin());
Linking.getInitialURL().then(async (url) => {
  if (url) {
    const didHandleURL = await handleURL(url);
    if (didHandleURL) {
      return;
    }
    // Handle a non-Amplitude SDK URL
  }
});
Linking.addEventListener("url", async ({ url }) => {
  const didHandleURL = await handleURL(url);
  if (didHandleURL) {
    return;
  }
  // Handle a non-Amplitude SDK URL
});

구성 옵션

플러그인 실행

플러그인을 부팅하면(사용자 ID를 사용하여) 가이드 및 설문조사를 표시할 수 있습니다:

import { boot } from "@amplitude/plugin-engagement-react-native";
import {
  track,
  setDeviceId,
  setUserId,
} from "@amplitude/analytics-react-native";
import { useEffect } from "react";
export default function App() {
  useEffect(() => {
    //
    // setting the User ID in @amplitude/analytics-react-native
    // --and-- passing it to boot() is necessary
    //
    setUserId("rn-test-user-1");
    setDeviceId("test-device-1");
    // boot(user_id?: string, device_id?: string, user_properties?: Object): void
    boot(
      "rn-test-user-1" /* user_id */,
      "test-device-1" /* device_id */,
      {} /* user_properties */,
    );
  }, []);
}

프로젝트 설정에 애플리케이션 추가

SDK를 설치한 후, React Native 애플리케이션을 Amplitude 프로젝트 설정에 추가하여 가이드 및 설문조사를 만들 때 플랫폼 옵션으로 나타나도록 하십시오.

애플리케이션을 추가하려면 다음과 같이 하십시오.

1. Amplitude에서 _설정 > 프로젝트_로 이동합니다.
2. 프로젝트를 선택합니다.
3. 가이드 및 설문조사 탭으로 이동합니다.
4. 앱 관리 섹션에서 확장하고 + 앱 추가를 클릭합니다.
5. 드롭다운에서 React Native를 선택합니다.

애플리케이션을 추가한 후에는 React Native 앱 사용자를 위한 가이드 및 설문조사를 만들거나 편집할 때 이를 플랫폼 옵션으로 선택할 수 있습니다.

미리보기 모드 설정 및 확인

애플리케이션에서 직접 가이드 및 설문조사를 미리 보고 사용자에게 제공되는 것과 동일한 경험을 확인하십시오. 미리 보기를 사용하면 문구, 타겟팅 규칙 및 트리거 로직을 쉽게 반복할 수 있으며 설치가 제대로 작동하는지 확인할 수 있습니다.

Xcode에서 미리보기 설정하기(iOS)

모바일 URL 체계 찾기

URL 체계를 찾으려면 다음과 같이 하십시오.

1. Amplitude에서 _설정 > 프로젝트_로 이동합니다.
2. 프로젝트를 선택합니다.
3. 일반 탭으로 이동합니다.
4. URL 스키마(모바일) 필드를 찾습니다.
5. 해당 값을 복사합니다(예: amp-abcdefgh12345678).

Xcode에서 URL 스키마를 추가합니다

1. Xcode에서 iOS 프로젝트를 엽니다.
2. 프로젝트 내비게이터에서 앱의 타겟을 선택합니다.
3. Info 탭에서 URL Types 섹션을 찾거나 추가합니다.
4. 다음 값을 사용하여 새 URL 유형을 추가합니다.
   • URL 식별자: AmplitudeURLScheme와 같이 설명이 잘 되는 이름을 입력하십시오.
   • URL 구성표: Amplitude에서 복사한 값을 붙여넣습니다(예: amp-abc123).

Android Studio에서 미리보기 설정하기 (Android)

모바일 URL 체계 찾기

URL 체계를 찾으려면 다음과 같이 하십시오.

1. Amplitude에서 _설정 > 프로젝트_로 이동합니다.
2. 프로젝트를 선택합니다.
3. 일반 탭으로 이동합니다.
4. URL 스키마(모바일) 필드를 찾습니다.
5. 해당 값을 복사합니다(예: amp-abcdefgh12345678).

Android Studio에서 URL 스키마 추가

다음 인텐트 필터를 프로젝트의 AndroidManifest.xml 파일 내 메인 액티비티에 추가하십시오.

<activity android:name=".MainActivity">
    <intent-filter>
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <!-- Add your URL scheme from Amplitude Dashboard here -->
    <!-- ex: android:scheme="amp-12345" -->
    <data android:scheme="<your-unique-scheme-id>" />
    </intent-filter>
</activity>

미리보기 링크에 대한 URL 처리

초기화 코드 조각은 미리보기 링크의 URL 처리를 수행합니다. 관련 코드는 다음과 같습니다.

Linking.getInitialURL().then(async (url) => {
  if (url) {
    const didHandleURL = await handleURL(url);
    if (didHandleURL) {
      return;
    }
    // Handle a non-Amplitude SDK URL
  }
});
Linking.addEventListener("url", async ({ url }) => {
  const didHandleURL = await handleURL(url);
  if (didHandleURL) {
    return;
  }
  // Handle a non-Amplitude SDK URL
});

QR 코드 스캔을 통해 설치 상태를 확인하십시오.

설치가 처음부터 끝까지 제대로 작동하는지 확인하십시오.

1. Amplitude에서 가이드 또는 설문조사를 열고 미리보기를 클릭합니다.
2. 기기의 카메라로 표시된 QR 코드를 스캔하거나, 앱이 설치된 기기에서 미리보기 URL을 엽니다.
3. 앱 내에서 가이드 또는 설문조사가 열리는지 확인하십시오.
4. 화면 하단에 있는 작은 Amplitude 로고를 찾아 누르면 슈퍼 디버거가 열립니다. 여기서 확인할 내용은 슈퍼 디버거를 참조하십시오.

앱에서 미리보기가 열리지 않거나 로고가 나타나지 않는 경우, 계속하기 전에 위의 딥링크 및 URL 구성표 설정 단계를 검토하십시오.

참조

최소 SDK 버전 설정(필요한 경우)

모바일 SDK 버전 3.0.0 및 이후 버전에서 Minimum SDK version을(를) 지원합니다. 이전 SDK 릴리스에서 심각한 문제를 확인할 때 이 설정을 안전 제어로 사용하십시오.

최소 SDK 버전을 구성하려면 다음과 같이 하십시오.

1. Amplitude에서 _설정 > 프로젝트_로 이동합니다.
2. 프로젝트를 선택합니다.
3. 가이드 및 설문조사 탭으로 이동합니다.
4. 앱 관리 섹션에서 확장하고 + 앱 추가를 클릭합니다.
5. 드롭다운에서 React Native를 선택합니다.
6. 최소 SDK 버전에 값을 입력합니다.

이 값을 설정하면 가이드 및 설문조사는 각 앱 빌드의 SDK 버전과 구성된 최소 값을 비교합니다.

• 앱 빌드에서 이전 SDK 버전을 사용하는 경우 SDK가 해당 빌드에서 초기화되지 않습니다.
• 앱 빌드에서 동일하거나 최신 버전의 SDK를 사용하는 경우 SDK가 예상대로 초기화됩니다.

이 설정을 사용하면 애플리케이션 릴리스를 롤백하지 않고 문제가 있는 알려진 SDK 버전에서 가이드 및 설문조사를 중지할 수 있습니다.

최소 SDK 버전의 사용 예제

앱 버전 120이 가이드 및 설문조사 SDK 3.0.2를 사용하고, 앱 버전 121이 버그 수정이 포함된 가이드 및 설문조사 SDK 3.1.0를 사용한다고 가정해 보겠습니다. 최소 SDK 버전을 다음과 같이 3.1.0설정한 경우

• 앱 버전120은 더 이상 가이드 및 설문조사를 로드하지 않습니다.
• 앱 버전121은 계속해서 가이드 및 설문조사를 로드합니다.

요소 타겟팅

핀, 툴팁 및 카드 삽입 가이드는 SDK가 화면의 특정 뷰를 대상으로 설정해야 합니다. Engagement SDK는 React Native DOM 내의 요소에 대한 testID속성을 사용합니다.

다음 예제에서는 가이드 및 설문조사 대시보드에서 welcome-banner을 요소 타겟팅 문자열로 사용하십시오.

import React from "react";
import { View, Text, StyleSheet } from "react-native";
/**
 * A simple component with a testID that can be targeted
 * by the Amplitude Guides & Surveys SDK.
 */
export default function WelcomeBanner() {
  return (
    <View
      testID="welcome-banner" // Element targeting through testID
      style={styles.banner}
    >
      <Text style={styles.bannerText}>Welcome to the App!</Text>
    </View>
  );
}

현지화

초기화 시 locale옵션을 설정하지 않을 경우 SDK는 기본적으로 기기의 시스템 언어를 사용합니다. 기본값은 언어 코드만(예: en)이며, en-US와 같은 전체 로케일 식별자는 아닙니다.

특정 언어를 설정하려면 SDK를 초기화할 때 locale 옵션을 전달하십시오.

import { init, add } from "@amplitude/analytics-react-native";
import { getPlugin } from "@amplitude/plugin-engagement-react-native";
init("YOUR_API_KEY");
add(
  getPlugin({
    locale: "es-ES",
  }),
);

슈퍼 디버거

Amplitude 대시보드에서 미리보기 QR 코드를 스캔하면 화면 하단에 작은 Amplitude 로고가 나타납니다. 이를 눌러 슈퍼 디버거 패널을 엽니다.

슈퍼 디버거에는 세부 정보와 설정이라는 두 가지 탭이 있습니다.

세부 정보 탭

세부 정보 탭에는 미리 보고 있는 가이드 또는 설문조사에 대한 정보가 표시되며 미리 보기 세션을 검토하고 제어할 수 있습니다.

가이드/설문조사: 활성 가이드나 설문조사의 이름입니다. 이를 탭하여 다른 가이드나 설문조사로 전환하세요.

세부 정보:

• 단계: 총 단계 중 현재 단계 번호입니다(예: "3단계 중 1"). 복사 아이콘을 눌러 값을 복사합니다.
• 사용자: 미리 보기 세션의 사용자 ID입니다. 복사 아이콘을 눌러 이를 복사합니다.
• 화면: SDK가 현재 보고하는 화면 이름입니다. 복사 아이콘을 눌러 이를 복사합니다.

디버그: 가이드 또는 설문조사가 각 조건 검사를 통과했는지 여부를 표시합니다. 각 행은 확장되어 세부 정보를 표시합니다.

• 제한: 가이드 또는 설문조사가 표시 제한에 도달했는지 여부입니다. 확장하여 구성된 제한을 검토합니다.
• 트리거: 가이드 또는 설문조사가 트리거 조건을 충족하는지 여부입니다. 트리거 유형, 화면 조건 및 핀 대상 요소(해당되는 경우)를 검토하려면 확장합니다.
• 스로틀: 가이드 또는 설문조사가 스로틀 조건을 충족하는지 여부입니다. 스로틀 설정을 검토하려면 확장합니다. 미리보기 세션 동안 스로틀 제한을 우회하려면 제한 무시를 토글합니다.

고급:

• 핀 디버깅: 5초마다 핀 위치 변경을 활성화하도록 확장합니다. 디버거는 동적 레이아웃에서의 핀 배치를 디버깅하는 데 도움이 되도록 핀 위치를 정기적으로 재평가합니다.

패널 맨 아래에:

• 미리 보기 다시 시작: 가이드 또는 설문조사를 첫 번째 단계로 재설정하고 미리 보기를 다시 시작합니다.
• 미리 보기 닫기: 미리 보기 모드를 종료하고 수퍼 디버거를 종료합니다.

설정 탭

설정 탭에는 현재 세션에 대한 SDK 구성 및 환경 세부 정보가 표시됩니다.

SDK 버전: 앱에 설치된 참여 SDK의 버전입니다.

설치:

• 유형: SDK 설치 방법(예: 플러그인 또는 독립형)입니다.
• 구성: 적용된 사용자 지정 구성 옵션의 수와 유형입니다.

사용자:

• 사용자 ID: 부팅 시 SDK에 전달된 사용자 ID입니다.
• 속성: 현재 세션에 대해 설정된 사용자 속성입니다.

이벤트 흐름: 이벤트가 올바르게 흐르고 있는지 확인합니다:

• 가이드 및 설문조사 SDK로 흐르는 이벤트: 분석 인스턴스의 이벤트는 참여 SDK에 도달합니다.
• 가이드 및 설문조사 SDK에서 발생하는 이벤트: 참여 SDK는 이벤트를 Amplitude로 전송합니다.

지원

**?**를 누르십시오. 지원 패널을 여는 버튼입니다. 여기에서 다음을 수행할 수 있습니다.

• SDK 문서와 가이드 및 설문조사 요약에 대한 링크를 엽니다.
• 버그 리포트 제출: 디버거에서 직접 버그 리포트를 제출합니다. 재현할 단계, 예상 결과 및 실제 결과를 입력한 다음 보내기를 누릅니다.

알려진 제한 사항

탭 바 요소 타겟팅

핀과 툴팁은 탐색 구성 요소(예: @react-navigation/bottom-tabs)의 탭 막대 항목을 대상으로 삼을 수 없습니다. 탭 바는 표준 React Native 뷰 계층 구조 외부에 존재하는 네이티브 컴포넌트를 사용하므로, SDK가 안정적으로 이러한 요소를 찾아 가이드를 연결할 수 없습니다.

애니메이션된 요소와 움직이는 컨테이너 내부의 요소를 대상으로 설정

핀과 툴팁은 다음과 같은 뷰나 요소를 대상으로 삼을 수 없습니다.

• 애니메이션되거나 애니메이션된 컨테이너에 있습니다(화면 주위를 이동).
• 사용자 상호 작용에 따라 이동할 수 있는 컨테이너에 있습니다.

변경 기록

Mobile SDK 변경 기록으로 이동하십시오.