가이드 및 설문조사 Flutter SDK

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

설치 및 확인

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

요구 사항

가이드 및 설문조사 Flutter SDK를 사용하려면 다음이 필요합니다.

• Dart 3.3 이상.
• Flutter 3.7 이상.
• Amplitude 애널리틱스 Flutter SDK 4.4.0 이상.

설치

SDK 설치

가이드 및 설문조사 패키지와 Amplitude 분석 SDK를 pubspec.yaml에 추가하십시오:

dependencies:
  amplitude_flutter: ^4.4.0
  amplitude_engagement_flutter: ^0.0.5

flutter pub get을(를) 실행하여 종속성을 설치합니다.

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

cd ios
pod install

SDK 초기화

import 'package:app_links/app_links.dart';
import 'package:amplitude_flutter/amplitude.dart';
import 'package:amplitude_flutter/configuration.dart';
import 'package:amplitude_engagement_flutter/amplitude_engagement.dart' as engagement;
// Initialize Analytics
final amplitude = Amplitude(Configuration(apiKey: 'YOUR_API_KEY'));
// Connect the engagement SDK to the analytics instance
await engagement.installAmplitudeEngagementPlugin(amplitude);
// Handle deep links for preview mode
final appLinks = AppLinks();
appLinks.getInitialLink().then((uri) async {
  if (uri != null) {
    final didHandleURL = await engagement.handleURL(uri.toString());
    if (didHandleURL) { return; }
    // Handle a non-Amplitude SDK URL
  }
});
appLinks.uriLinkStream.listen((uri) async {
  final didHandleURL = await engagement.handleURL(uri.toString());
  if (didHandleURL) { return; }
  // Handle a non-Amplitude SDK URL
});

installAmplitudeEngagementPlugin는 동일한 API 키를 사용하여 참여 SDK를 초기화하고 네이티브 분석 인스턴스를 iOS 및 Android의 참여 계층으로 전달합니다.

구성 옵션

SDK를 구성하려면 AmplitudeInitOptions 객체를 installAmplitudeEngagementPlugin에 전달하십시오.

await engagement.installAmplitudeEngagementPlugin(amplitude, options: AmplitudeInitOptions(
  serverZone: AmplitudeServerZone.eu,
  logLevel: AmplitudeLogLevel.debug,
));

SDK 부팅

사용자 ID로 SDK를 부팅하여 가이드 및 설문조사를 활성화하십시오.

import 'package:amplitude_flutter/amplitude.dart';
import 'package:amplitude_flutter/events/identify.dart';
import 'package:amplitude_engagement_flutter/amplitude_engagement.dart' as engagement;
// Setting the User ID in Amplitude Analytics
// --and-- passing it to boot() is necessary
amplitude.setUserId('test-user-1');
// boot(userId, deviceId, userProperties)
await engagement.boot(
  userId: 'test-user-1',
  deviceId: 'test-device-1', // optional if userId is set
  userProperties: {'plan': 'premium'}, // optional
);

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

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

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

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

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

미리보기 모드 설정 및 확인

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

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 처리를 수행합니다. 관련 코드는 다음과 같습니다.

final appLinks = AppLinks();
appLinks.getInitialLink().then((uri) async {
  if (uri != null) {
    final didHandleURL = await engagement.handleURL(uri.toString());
    if (didHandleURL) { return; }
    // Handle a non-Amplitude SDK URL
  }
});
appLinks.uriLinkStream.listen((uri) async {
  final didHandleURL = await engagement.handleURL(uri.toString());
  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. 드롭다운에서 Flutter를 선택합니다.
6. 최소 SDK 버전에 값을 입력합니다.

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

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

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

화면 추적

화면 기반 타겟팅과 화면 시간 트리거를 활성화하려면 screen호출하십시오. 가이드 및 설문조사는 화면 문자열(예: "HomeScreen")을 가이드 또는 설문조사 페이지 타겟팅 섹션에서 설정한 문자열과 비교합니다.

engagement.screen('HomeScreen');

요소 타겟팅

핀, 툴팁 및 카드 삽입 가이드가 화면의 특정 위젯을 대상으로 하려면 SDK가 필요합니다. SDK는 초기화 시 요소 타겟팅을 자동으로 활성화합니다.

타겟팅 가능한 위젯에 AmplitudeEngagementView을 SemanticsTag로 태그하여 안정적인 식별자를 부여하십시오. 다음 예제에서는 가이드 및 설문조사 대시보드에서 "welcome-banner"을 요소 타겟팅 문자열로 사용하십시오.

import 'package:flutter/material.dart';
import 'package:amplitude_engagement_flutter/amplitude_engagement.dart' as engagement;
Semantics(
  tagForChildren: const engagement.AmplitudeEngagementView('welcome-banner'),
  child: Banner(
    child: Text('Welcome to the app'),
  ),
)

현지화

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

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

import 'package:amplitude_flutter/amplitude.dart';
import 'package:amplitude_engagement_flutter/amplitude_engagement.dart' as engagement;
final amplitude = Amplitude(Configuration(apiKey: 'YOUR_API_KEY'));
await engagement.installAmplitudeEngagementPlugin(amplitude, options: AmplitudeInitOptions(
  locale: 'es-ES',
));

기타 SDK 방법

테마 관리

engagement.setThemeMode(AmplitudeThemeMode.dark); // Options: auto, light, dark

콜백 등록

engagement.addCallback('show-alert', () {
  // Custom logic when the guide or survey triggers this callback
});

재설정

engagement.reset('GUIDE_KEY', 0);

목록

final guidesAndSurveys = await engagement.list();

보기

engagement.show('GUIDE_KEY');

전달 이벤트

가이드 및 설문조사에서 이벤트 추적 시 트리거를 활성화하려면 forwardEvent를 사용하십시오. SDK는 전달된 이벤트를 Amplitude 서버로 전송하지 않습니다. 이러한 이벤트는 로컬 트리거 평가에만 사용합니다.

engagement.forwardEvent({
  'event_type': 'Button Clicked',
  'event_properties': {'name': 'Submit'},
});

모두 닫기

engagement.closeAll();

슈퍼 디버거

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

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

세부 정보 탭

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

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

세부 정보:

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

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

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

고급:

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

패널 맨 아래에:

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

설정 탭

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

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

설치:

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

사용자:

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

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

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

지원

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

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

알려진 제한 사항

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

핀과 툴팁은 다음과 같은 위젯을 타겟팅할 수 없습니다.

• 애니메이션되거나 애니메이션된 컨테이너 내부에 있습니다(화면에서 움직임).
• 사용자 상호 작용에 따라 이동하는 컨테이너 내부입니다.

변경 기록

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