ガイドとサーベイ React Native SDK

AmplitudeのガイドとサーベイSDKを使用すると、ウェブサイトやアプリケーションにガイドとサーベイをデプロイできます。

インストールと検証

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

要件

Guides and Surveys 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. App Management セクションを展開し、+ Add App をクリックします。
5. ドロップダウンから React Native を選択します。

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

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

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

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処理を行います。関連するコードは次のとおりです。

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

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

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

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

最小SDKバージョンの使用例

アプリバージョン120ではGuides and Surveys SDK3.0.2を使用しており、アプリバージョン121ではバグ修正が含まれるGuides and Surveys SDK3.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ロゴが表示されます。 これをタップすると、スーパーデバッガーパネルが開きます。

スーパーデバッガーには、詳細と設定という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ドキュメントやガイドとサーベイの概要へのリンクを開きます。
• バグレポートを提出する：デバッガーから直接バグレポートを送信できます。再現するステップ、予想される結果、実際の結果を入力してから、送信をタップします。

既知の制限事項

タブバー要素のターゲット設定

ピンやツールチップは、ナビゲーションコンポーネント（@react-navigation/bottom-tabsなど）のタブバー項目をターゲットにすることはできません。タブバーは標準の React Native ビュー階層の外に存在するネイティブコンポーネントを使用するため、SDK はこれらの要素を確実に検索してガイドを添付できません。

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

ピンやツールチップは、次のようなビューや要素をターゲットにすることはできません。

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

変更履歴

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