ガイドとサーベイ React Native SDK

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

インストールと検証

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

要件

ガイドとサーベイ React Native SDKには以下が必要です。

インストール

SDKをインストールする

ガイドとサーベイReact Native SDKをnpmまたはYarnを使用してパッケージとしてインストールします。

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

非同期ストレージ

@react-native-async-storage/async-storageを明示的に追加すると、engagementネイティブモジュールがそれを使用するため、ネイティブモジュールの正しいリンクを確保できます。

iosディレクトリでpod installを実行します。

bash
cd ios
bundle exec pod install

SDKの初期化

js
//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
});

Amplitudeサーバーゾーン

SDKは、@amplitude/analytics-react-nativeを初期化するserverZoneを自動的に使用します。SDK の設定を参照してください。 initを実行するにあたり、options引数にserverZoneを渡す必要はありません。

設定オプション

ガイドとサーベイとアナリティクスに同じ API キーを使用してください。

アナリティクスのミスマッチを回避し、正確なデータ収集を確保するには、ガイドとサーベイとアナリティクス SDK の両方に同じ API キーを使用してください。両方で、同じAmplitudeプロジェクトを参照する必要があります。異なるAPIキーを使用すると、次のような問題が発生する可能性があります。

  • SDKが間違ったプロジェクトからガイドやサーベイを取得する。
  • アナリティクスデータが異なるプロジェクトに表示される。
  • インサイトとアンケート回答が不完全であるか、または不一致である。

ガイドとサーベイに提供するAPIキーが、Amplitude アナリティクス SDKの初期化に使用したAPIキーと一致していることを確認してください。

プラグインを起動する

プラグインを起動すると(ユーザーIDを使用)、ガイドとサーベイを表示できます。

js
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 */,
    );
  }, []);
}

boot はオプションオブジェクトも受け取ります。アプリでAmplitude アナリティクス React Native SDKを使用していない場合は、その呼び出しにintegrationsを含めます。

Amplitudeアナリティクスプラグインを使用していない場合の必須設定

  • 必須: ガイドとサーベイのイベントをアナリティクスプロバイダーに送信するために、boot 呼び出しにintegrations を含めてください。これがないと、ガイドインサイト、サーベイインサイト、サーベイ回答は表示されません。
js
import { boot } from "@amplitude/plugin-engagement-react-native";
// Basic boot with user ID
boot("USER_ID");
// Advanced boot with options
boot({
  user: {
    user_id: "USER_ID",
    device_id: "DEVICE_ID",
    user_properties: { key: "value" },
  },
  integrations: [
    (eventType, eventProperties) => {
      // Custom event handler
    },
  ],
});

プラグインを起動すると、インストールは完了します。 引き続きプレビューモードの設定と検証に進み、すべてが正常に動作することを確認してください。

アプリケーションをプロジェクト設定に追加する

SDKをインストールした後、React NativeアプリケーションをAmplitudeプロジェクト設定に追加してください。これにより、ガイドやサーベイを作成するときにプラットフォームオプションとして表示されます。

アプリケーションを追加するには:

  1. Amplitudeの_設定 > プロジェクト_に移動します。
  2. プロジェクトを選択します。
  3. ガイドとサーベイタブに移動します。
  4. App Management セクションを展開し、+ Add App をクリックします。
  5. ドロップダウンから React Native を選択します。

アプリケーションを追加した後、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 ファイルのメインアクティビティに次のインテントフィルターを追加します。

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

js
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ではガイドとサーベイ SDK3.0.2を使用しており、アプリバージョン121ではバグ修正が含まれるガイドとサーベイ SDK3.1.0を使用しているとします。最小SDKバージョンを3.1.0に設定すると次のようになります。

  • アプリのバージョン120では、ガイドとサーベイが読み込まれなくなりました。
  • アプリのバージョン121は引き続きガイドとサーベイを読み込みます。

画面追跡と要素ターゲティング

画面追跡と要素ターゲティングはオプションですが、ガイドやサーベイをよりターゲットに絞るのに役立ちます。

画面追跡を有効にする

画面ベースのターゲティングと画面表示時間トリガーについては、screenを呼び出してください。ガイドとサーベイでは、画面の文字列(たとえば「HomeScreen」)をガイドまたはサーベイページのターゲティングセクション内の文字列と比較します。

js
import { screen } from "@amplitude/plugin-engagement-react-native";
// Track screen views to trigger guides based on screens
screen("HomeScreen");

Amplitude アナリティクスプラグインは、[Amplitude] Screen Viewedイベントをエンゲージメント SDK に転送します。getPlugin()にignoreAnalyticsAutomaticScreenTracking: trueを渡して、その転送を停止します。

ピン、ツールチップ、カード埋め込みガイドでは、SDK が画面上の特定のビューをターゲットにする必要があります。 ピンとツールチップは、ターゲットビューにオーバーレイをアンカーしますが、カード埋め込みはビューの前、後、または代わりにインラインでレンダリングされます。 この2つは異なるAPIを使用していますが、どちらの場合も、React Nativeで設定した識別子が、ガイドとサーベイダッシュボードのガイドで設定した要素ターゲット文字列と一致している必要があります。

ピンとツールチップ

Engagement SDKはReact Native DOM内の要素のtestIDプロパティを使用します。次の例では、ガイドとサーベイのダッシュボードで要素ターゲット文字列としてwelcome-bannerを使用してください。

js
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>
  );
}

カード埋め込み

カードの埋め込みはインラインでレンダリングされるため、このAmplitudeCardEmbedViewコンポーネントを使用します。ターゲットをAmplitudeCardEmbedViewでラップし、identifierを付与します。カードの埋め込みガイドがその識別子をターゲットに設定した場合、カードはレイアウト内のスペースを占有し、周囲のコンテンツは押し出されます。SDKは、ダッシュボードで設定した位置に基づいて、カードを子の前、後、またはその代わりにレンダリングします。

js
import { Text } from "react-native";
import { AmplitudeCardEmbedView } from "@amplitude/plugin-engagement-react-native";
export default function WelcomeBanner() {
  return (
    <AmplitudeCardEmbedView identifier="welcome-banner">
      <Text>Welcome to the App!</Text>
    </AmplitudeCardEmbedView>
  );
}

AmplitudeCardEmbedViewはその親の幅を埋めるため、ガイドで設定した幅と整列がカードにも適用されます。単独のtestIDでもビューをターゲットにできますが、その場合カードはスペースを占有せず、周囲のコンテンツに重なります。カード埋め込みにはAmplitudeCardEmbedViewを、ピンやツールチップにはtestIDを使用してください。

ローカリゼーション

初期化時にlocaleオプションを設定しない場合、SDKはデバイスのシステム言語をデフォルトで使用します。デフォルトは言語コードのみ(例:en)であり、en-USのような完全なロケール識別子ではありません。

特定の言語に設定するには、SDKを初期化するときにlocaleオプションを渡してください。

js
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",
  }),
);

SDK の初期化後に言語を動的に更新するには、このupdateLanguageメソッドを使用します。 呼び出しを行うと、新しいロケールで設定がupdateLanguage再取得されます。

js
updateLanguage(locale: string): Promise<void>
js
import { updateLanguage } from "@amplitude/plugin-engagement-react-native";
// Example: Update language to French with full locale
updateLanguage("fr-FR");
// Example: Update language to English with language code
updateLanguage("en");

その他のSDKメソッド

SDKを有効化および無効化する

disable()を使用して、ガイドやサーベイが一時的に表示されないようにしたり、現在表示されているものを非表示にしたりします。通常動作を再開するには、enable()を使用してください。

js
import { disable, enable } from "@amplitude/plugin-engagement-react-native";
// Temporarily disable the SDK
disable();
// Re-enable the SDK
enable();

セッションプロパティを設定する

現在のセッションのセッションプロパティを設定します。セッションプロパティは、ガイドやサーベイがいつトリガーされるかを制限するための追加の方法を提供します。トリガー時に、ガイドまたはサーベイが表示されるのは、設定されたセッション プロパティ条件が一致した場合だけです。

セッションのプロパティが変更されると、SDKは表示できるガイドやサーベイを確認します。セッション プロパティは「immediately」トリガーと連動し、セッション プロパティの条件が真になるとすぐにコンテンツを表示します。

文字列、数値、またはブール値を渡します。 SDKは、nullを含むその他の値を無視します。

js
setSessionProperty(key: string, value: string | number | boolean): Promise<void>

機能の可用性

:セッションプロパティは、フィーチャーフラグによる機能です。実装でこの機能を使用したい場合は、Amplitudeサポートまでお問い合わせください。

js
import { setSessionProperty } from "@amplitude/plugin-engagement-react-native";
// Various session properties to control guide/survey targeting
await setSessionProperty("subscriptionTier", "premium");
await setSessionProperty("isFeatureXEnabled", true);
await setSessionProperty("userScore", 85);

ボタンコールバックを登録する

Runコールバックアクションを使用して、ユーザーがガイドまたはサーベイのボタンをタップしたときに実行される関数を登録します。addCallbackに渡すキーは、そのボタンに入力したコールバック名と一致している必要があります。

js
addCallback(key: string, func: () => void): () => void

addCallbackは、コールバックを削除する関数を返します。

js
import { Alert } from "react-native";
import { addCallback } from "@amplitude/plugin-engagement-react-native";
addCallback("show-alert", () => {
  Alert.alert("Callback", "Callback has been executed!");
});

ルータの設定

ガイドとサーベイが画面ナビゲーションを処理する方法を設定します。

js
import { setRouter } from "@amplitude/plugin-engagement-react-native";
setRouter((url) => {
  // Your screen handling and navigation
});

リンク動作を更新する

setRouter() を使用してルーターを構成した後、ガイドとサーベイのインターフェイスでリンク動作設定を更新します。ガイドやサーベイでリンクアクションを行う場合は、動作を [ルーターを使用] に変更してください。その後、ガイドまたは調査では、デフォルトのブラウザナビゲーションではなくカスタムルーター機能が使用されます。

ルーターを削除するには、unsetRouter() にお電話ください。

js
import { unsetRouter } from "@amplitude/plugin-engagement-react-native";
unsetRouter();

List

すべてのライブガイドとサーベイのリストとそのステータスを取得できます。

js
import { list } from "@amplitude/plugin-engagement-react-native";
const guidesAndSurveys = await list();

表示する

特定のガイドやアンケートを表示します。画面ターゲット設定以外のターゲット設定ルールや制限を無視します。

js
import { show } from "@amplitude/plugin-engagement-react-native";
show("GUIDE_KEY", 0);

イベントを転送する

Amplitude アナリティクス React Native SDK プラグインを使用していない場合(つまり、bootを直接呼び出した場合)、forwardEventを使用してガイドとサーベイで_イベント追跡_トリガーを有効にします。転送されたイベントはAmplitudeサーバーに送信されません。 SDK はこれらをローカル トリガー評価にのみ使用します。

このインストールパスに強く推奨:

Amplitudeは、Amplitude アナリティクス React Native SDKプラグインを使用していない場合、イベント転送を設定することを強く推奨します。これがないと、「On event tracked」トリガーを使用することはできません。そのため、アプリ内のユーザーの行動に基づいてガイドやサーベイを表示する機能が制限されます。

js
import { forwardEvent } from "@amplitude/plugin-engagement-react-native";
forwardEvent({
  event_type: "Button Clicked",
  event_properties: { name: "Submit" },
});

すべて閉じる

アクティブなすべてのガイドとサーベイを閉じます。

js
import { closeAll } from "@amplitude/plugin-engagement-react-native";
closeAll();

スーパーデバッガー

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

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

詳細タブ

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

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

詳細:

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

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

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

詳細設定:

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

パネルの下部:

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

設定タブ

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

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

インストール:

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

ユーザー:

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

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

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

サポート

**?**をタップします。_サポート_パネルを開くためのボタン。このビューでは以下を実行できます。

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

既知の制限事項

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

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

回避策

画面ベースのターゲティングまたはイベントベースのトリガーを使用して、ユーザーが特定のタブに移動したときにガイドを表示します。タブバーの項目に直接ピン留めしないでください。

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

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

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

注記

Scrollviewは通常、機能します。

回避策

画面ベースのターゲティングまたはイベントベースのトリガーを使用してガイドを表示します。アニメーションが確実に完了するように、遅延を設定することもあります。アニメーションコンテナやユーザーとのやり取りを通じて移動できるコンテナ内の要素に直接ピン留めしないでください。

ビューのフラット化と要素のターゲティング

React NativeはView Flatteningと呼ばれる機能をサポートしています。この機能はデフォルトで有効になっています。 React Nativeがビューをフラット化するとき、そのビューはネイティブのビュー階層から削除され、ピンガイドのターゲティングや「On element tapped」トリガーには使用できなくなります。

Workaround

Add collapsable={false} ビューに追加します。これにより、React Nativeはそれをフラット化できなくなり、ピンガイドのターゲティングと「On element tapped」トリガーに利用できます。

js
<View testID="my-element" collapsable={false}>
  {/* view content */}
</View>

変更履歴

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

これは役に立ちましたか?

For AI agents: a documentation index is available at /docs/llms.txt. Append .md to any page URL for markdown, or send Accept: text/markdown.

このページでは