ガイドとサーベイ Flutter SDK

AmplitudeのGuides and Surveys Flutter SDKを使用すると、Flutterアプリケーションにガイドとサーベイをデプロイできます。

インストールと検証

以下の手順に従ってSDKをインストールし、アプリをAmplitudeプロジェクトに接続し、ガイドやサーベイがアプリに届くことを確認してください。

要件

Guides and Surveys Flutter SDKには以下が必要です。

• Dart 3.3以降。
• Flutter 3.7 以降。
• Amplitude Analytics Flutter SDK 4.4.0 以降。

インストール

SDKをインストールする

ガイドおよびサーベイパッケージとAmplitude Analytics 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. App Management セクションを展開し、+ Add App をクリックします。
5. ドロップダウンからFlutterを選択します。

アプリケーションを追加した後、Flutterアプリユーザー向けのガイドやサーベイを作成または編集する際に、プラットフォームオプションとしてアプリケーションを選択できます。

プレビューモードの設定と検証

ガイドやサーベイをアプリケーション内で直接プレビューすることで、ユーザーと同じ体験を確認できます。プレビュー機能を使用すると、コピー、ターゲット設定ルール、トリガーロジックの繰り返し調整が容易になり、インストールが正常に動作していることを確認できます。

Xcode でプレビューを設定する (iOS)

モバイルURLスキームを特定する

URLスキームを特定するには：

1. Amplitudeの_設定 > プロジェクト_に移動します。
2. プロジェクトを選択します。
3. ［全般］タブに移動します。
4. **URLスキーム（モバイル）**フィールドを探します。
5. その値をコピーします（例：amp-abcdefgh12345678）。

XcodeでのURLスキームの追加

1. iOS プロジェクトを Xcode で開きます。
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. App Management セクションを展開し、+ Add App をクリックします。
5. ドロップダウンからFlutterを選択します。
6. 「Minimum SDK version」に値を入力します。

この値を設定すると、ガイドとサーベイは設定済みの最小値と各アプリビルドのSDKバージョンを比較します。

• アプリのビルドで古いバージョンの SDK を使用している場合、SDK はそのビルドで初期化されません。
• アプリのビルドで同じバージョンまたは新しいバージョンの SDK を使用している場合、SDK は期待どおりに初期化されます。

この設定を使用すると、アプリケーションリリースをロールバックすることなく、問題のある既知のSDKバージョンに関するガイドやサーベイを停止できます。

スクリーントラッキング

screenを呼び出して、画面ベースのターゲティングとTime on 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);

List

final guidesAndSurveys = await engagement.list();

表示する

engagement.show('GUIDE_KEY');

イベントを転送する

ガイドとサーベイで_On event tracked（イベントトラッキング時）_トリガーを有効にするには、forwardEventを使用します。SDKは転送されたイベントをAmplitudeサーバーに送信しません。これらのイベントはローカルのトリガー評価にのみ使用されます。

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

すべて閉じる

engagement.closeAll();

スーパーデバッガー

AmplitudeダッシュボードからプレビューQRコードをスキャンすると、画面下部に小さなAmplitudeロゴが表示されます。 これをタップすると、スーパーデバッガーパネルが開きます。

スーパーデバッガーには、詳細と設定という2つのタブがあります。

詳細タブ

_詳細_タブには、プレビューしているガイドまたはサーベイに関する情報が表示され、プレビューセッションの確認と制御を行うことができます。

ガイド / サーベイ：アクティブなガイドまたはサーベイの名前。タップすると、別のガイドやアンケートに切り替えることができます。

詳細:

• ステップ: 全ステップ数に対する現在のステップ番号 (たとえば、「1/3」)。コピーアイコンをタップして値をコピーします。
• ユーザー：プレビューセッションのユーザーID。コピーアイコンをタップしてコピーします。
• 画面：SDKが現在レポートしている画面名です。コピーアイコンをタップしてコピーします。

デバッグ: ガイドまたは調査が各条件チェックに合格したかどうかを示します。 各行が展開され、詳細が表示されます。

• 制限：ガイドまたはサーベイが表示制限に達したかどうか。展開して設定済みの制限を確認します。
• トリガー：ガイドまたは調査がトリガー条件を満たしているかどうか。展開すると、トリガータイプ、画面条件、ピンターゲット要素（該当する場合）を確認できます。
• スロットル：ガイドまたはサーベイがスロットル条件を満たしているかどうか。展開してスロットル設定を確認します。 <2>制限を無視する〼/2>をおんにすると、プレビューセッション中にスロットル制限を回避できます。

詳細設定：

• ピンのデバッグ：展開して、5秒ごとにピンの位置変更を有効にします。デバッガは定期的にピンの位置を再評価し、動的レイアウトでのピンの配置をデバッグするのに役立ちます。

パネルの下部：

• プレビューを再起動：ガイドまたは調査を最初のステップにリセットし、プレビューを再起動します。
• プレビューを閉じる: プレビュー モードを終了し、スーパー デバッガを閉じます。

設定タブ

_設定_タブには、現在のセッションのSDK設定と環境の詳細が表示されます。

SDK バージョン: アプリにインストールされている Engagement SDK のバージョンです。

インストール：

• タイプ：SDKのインストール方法（プラグインまたはスタンドアロンなど）。
• 構成：適用されるカスタム構成オプションの数とタイプ。

ユーザー:

• ユーザー ID: 起動時にSDKに渡されるユーザーIDです。
• プロパティ: 現在のセッションに設定されているすべてのユーザー プロパティ。

イベントフロー：イベントが正しく流れているかどうかを確認します：

• ガイドとサーベイSDKに流入するイベント: アナリティクスインスタンスからのイベントは、エンゲージメントSDKに到達します。
• Guides and Surveys SDKから送出されるイベント：Engagement SDKがイベントをAmplitudeに送信します。

サポート

**？**をタップします。_サポート_パネルを開くためのボタン。ここから次のことができます：

• SDKドキュメントやガイドとサーベイの概要へのリンクを開きます。
• バグレポートを提出する：デバッガーから直接バグレポートを送信できます。再現するステップ、予想される結果、実際の結果を入力してから、送信をタップします。

既知の制限事項

アニメーション化された要素と移動するコンテナ内の要素をターゲットに設定する

ピンやツールチップは、次のようなウィジェットをターゲットにすることはできません。

• アニメーション化されているか、アニメーション化されたコンテナ内です（画面上で移動します）。
• ユーザーの操作に基づいて移動するコンテナ内部。

変更履歴

モバイルSDKの変更履歴にアクセスしてください。