このページでは

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.

ガイドまたはアンケートが表示されない

表示されないガイドやアンケートは通常、5 つのチェックのうちの 1 つに失敗します。SDK がページまたはアプリで実行されていない、体験が適切なプロジェクトに公開されていない、ユーザーがターゲティングと一致していない、トリガーが起動しない、制限やスロットルが表示をブロックしているということです。 この順序でチェックを実行してください。これは、SDK の設定が壊れていると、他のすべてのチェックを評価することが不可能になるためです。

この記事では、ガイドやアンケートの設定方法を理解していることを前提としています。 再確認が必要な場合は、次に進む前に「設定とターゲティング」を確認してください。 その体験が予想以上に頻繁に表示される場合は、「頻繁に表示されるガイドまたはアンケート」にアクセスしてください。

プレビューモードとプラットフォームツールを使用したデバッグ

設定を変更する前に、どの条件が失敗しているかをレポートするツールを使用してください。 これにより、推測する必要がなくなります。

ウェブ：Chrome 拡張機能とプレビューモード

Amplitude Chrome拡張機能は、表示されないウェブガイドやアンケートを診断するための最速の方法です。 ガイドとサーベイタブのレポート:

  • SDK の設定: SDK がインストールされ、初期化され、分析 SDK に接続され、起動されているかどうか、さらに Show config の API キーと Show user info の解決済みユーザー。
  • トリガー条件: プロジェクト内のすべての公開ガイドとアンケートについて、どの条件が合格し、どの条件が表示をブロックするかを示します。内蔵スロットル、カスタムスロットル、制限、ページターゲティング、スヌーズ、ユーザーターゲティングなどが含まれます。
  • 転送されたイベント: SDK が監視するすべてのクライアント側イベント。 イベント名を入力し、「テスト イベント」をクリックしてイベントをシミュレートし、イベントベースのトリガーが起動することを確認します。

この拡張機能の*「ガイドとサーベイ」*タブはリアルタイムで更新されないため、ページの読み込みが完了するまで待ってからお読みください。

プレビューモードでは、単一の体験を実際のページと照合します。 プレビューバーにはトリガー、制限、およびスロットルの各条件が表示されます。緑色は条件が合格したことを意味し、黄色は表示がブロックされていることを意味します。 プレビューバーから「ユーザー履歴のリセット」をクリックしたり、「スロットル制限を無視」を切り替えたり、トリガーが待機するイベントを手動でトリガーすることもできます。プレビュー自体が表示されない場合は、「トラブルシューティング プレビュー モード」に移動してください。これには、window.postMessage障害およびCross-Origin-Opener-Policyヘッダーに関する情報が含まれています。

モバイル: スーパーデバッガとプレビューモード

モバイルでは、プレビューモードでQRコードとプレビューURLが表示されます。 アプリがインストールされているデバイスでコードをスキャンするか、そのデバイスで URL を開きます。 SDK と URL スキームを設定すると、画面下部に小さな Amplitude ロゴが表示されたままアプリが開きます。 ロゴをタップすると、スーパーデバッガが開きます。

「スーパーデバッガの詳細」タブには、制限値、トリガー（画面状態とピンターゲットを含む）、およびスロットルが報告されます。 **[無視] **を切り替え、プレビュー期間中にスロットルをバイパスします。[セットアップ] タブでは、SDK のバージョン、インストールタイプ、ユーザー ID、およびガイドとサーベイ SDK との間でイベントが流れ出ているかどうかが報告されます。スーパーデバッガに移動して、パネル全体を表示してください。 Android、React Native、Flutter の SDK には同じデバッガーが含まれています。

アプリでプレビューモードが実行されない場合：

  • iOS ではNo usable data found：デバイスにはプレビュー URL を処理するアプリがありません。アプリがその iOS デバイスにインストールされていないか、インストールされたビルドがプロジェクトのモバイル URL スキームを登録していない場合。 ガイドとサーベイ SDK と URL スキームを含むビルドをインストールし、デバイスのカメラで QR コードをスキャンします。
  • Androidのアクションシートにはアプリが記載されていません：同じ原因です。 OS にはプレビュー URL を処理するアプリがないため、共有シートや open-with シートには何も表示されません。 SDK と URL スキーム用のインテントフィルタを含むビルドをインストールします。 Android プレビュー設定に移動します。
  • プレビューはアプリではなくブラウザで開きます。URL スキームを登録していないか、アプリがリンクを受信したときにhandleUrl（iOS）またはhandleLinkIntent（Android）を呼び出さない場合があります。

プレビューモードではレンダリングと条件を確認できますが、実際の配信ではありません。 実際のユーザーに対して配信をテストするには、[テスト中] ステータスを使用します。

トラブルシューティングのチェックリスト

これらの質問をチェックリストとして使用してください。 質問に対して「はい」と回答できる場合、その設定が問題の原因である可能性は低いです。

SDK はページ上またはアプリ内にインストールおよび起動されていますか？

ウェブ上で、ブラウザコンソールを開き、window.engagement と入力します。 undefinedの応答は、ガイドとサーベイ SDK がそのページにインストールされていないことを意味します。次に、window.engagement._debugStatus() を入力して、userオブジェクトが存在し、apiKey設定されており、stateInitialized両方ともdecideSuccessful であり、trueかつnum_guides_surveys がゼロより大きいことを確認します。

ウェブインストールでよく発生する問題としては、一部のページではロードされない SDK や、特定の環境やユーザータイプに対して条件付きで実行される呼び出し、boot複数回実行される呼び出し、bootAmplitude Browser SDK よりも先にロードされるガイドとサーベイ SDK などがあります。カスタム HTML タグを使用して Google タグマネージャー経由でインストールする場合、タグの詳細設定で Support document.write を有効にします。 完全なリストについては、「インストールのトラブルシューティング」を参照してください。

モバイルでは、ブラウザーコンソールではなく「スーパーデバッガ設定」タブを使用してください。 SDK のバージョンが表示されていること、ユーザー ID が想定するユーザーと一致していること、およびイベントがガイドとサーベイ SDK に流れていることを確認してください。プレビューモードでAmplitudeロゴが表示されない場合、SDKはプレビューURLを処理していません。 プロジェクトの URL スキームを追加したこと、およびアプリがインバウンドリンクを SDK に転送することを確認します。

API キーは、体験を保持するプロジェクトと一致していますか？

SDK は、その API キーに関連付けられたプロジェクトのガイドとサーベイを取得します。別のプロジェクトのキーを使用して SDK を初期化した場合、設定が正しく見えてもエクスペリエンスがロードされません。コアとなる Amplitude SDK とガイドとサーベイ SDK に同じ API キーを使用し、そのキーがエクスペリエンスを公開したプロジェクトに属していることを確認してください。

ステータスは公開済みですか？スケジュールはアクティブですか？

下書きエクスペリエンスはユーザーには表示されません。テスト エクスペリエンスは、[テスト ユーザー] セクションのデバイス ID、ユーザー ID、およびコホートに対してのみ表示されます。スケジュール済みの体験の場合、現在の時刻が開始日と終了日の間に該当することを確認してください。また、これらの回数はプロジェクトのタイムゾーンを使用していることに注意してください。また、一括公開解除により体験がオフラインになったかどうかを確認してください。

ユーザーはあなたのターゲットと一致していますか？

ターゲット設定セグメントを開き、影響を受けるユーザーがそのうちの少なくとも 1 つに一致することを確認してください。 Amplitude ORは複数のセグメントを持つため、ユーザーは 1 つだけに一致する必要がありますが、セグメント期間のすべてのフィルタは一致する必要があります。

これらのターゲット設定の原因に注意してください：

  • ロールアウトの割合が 100% 未満の場合、バケット外のユーザーは除外されます。 バケット化ユニットは、その割り当てがユーザーのデバイス間で一貫性を保つかどうかを決定します。
  • 配列のユーザープロパティは評価時にフラット化されないため、ドット付きパス (subscription.planなど) は解決されません。 代わりに、フラットスカラープロパティをターゲットにしてください。
  • コホートメンバーシップはスケジュールに基づいて同期されるため、資格を得たばかりのユーザーはまだ一致しません。 同期ルールについては、「コホートターゲティング」に移動します。
  • フィルタが読み取るユーザープロパティは、評価時点でユーザーのプロファイルに存在していない可能性があります。
  • プロジェクト全体のデフォルトのユーザー除外は、体験自体のターゲティングに加えて適用されます。 プロジェクト全体の除外セグメントに一致するユーザーは、たとえそれが体験のターゲティングと一致していたとしても、プロジェクト内でガイドやアンケートを見ることはありません。
  • グループコホートターゲティングを行うには、各ユーザーに対してsetGroupインストゥルメンテーションを呼び出す必要があります。グループプロパティをイベントに付加すると、イベントレベルのグループ化が作成されます。これは分析をサポートしますが、ユーザーをグループコホートターゲティングに適格にするものではありません。 詳細については、「グループコホートターゲティングではイベントレベルのグループを使用する」を参照してください。

このユーザーに対してトリガーが起動しますか？

トリガーがユーザーが実際に実行している操作と一致していることを確認します。

  • None トリガーは単独では起動しません。 これは、SDK、別のガイドでのアクションへの呼びかけ、または別の外部トリガーを待機します。
  • イベント追跡対象の場合、SDK が監視できるクライアント側のイベントが必要です。 サーバー側のイベント、ラベル付きイベント、カスタムイベントはトリガーとして機能しません。 ウェブ上で、拡張機能の [転送済みイベント] リストを確認して、SDK がイベントを認識していることを確認してください。 モバイルでは、「スーパーデバッガのセットアップ」タブで「イベントフロー」を確認してください。
  • 「要素が表示されると」は、ページまたは画面の読み込みごとに一度だけ起動し、要素が画面から外へスクロールして戻っても再起動しません。
  • **「要素がクリック/タップされた場合」**および「要素ベースの条件」は、まだマッチングしているセレクターに依存します。ウェブ上では、これは現在のマークアップに対する CSS セレクターまたは XPath です。 クラス名を変更するような再設計はセレクタを壊します。 モバイルでは、これはターゲットビュー上の固有の識別子です (accessibilityIdentifieriOStag では、contentDescriptionAndroidresourceName では、.amplitudeViewまたはAmplitudeView Jetpack Compose tagに渡されるもの)。2 つのビューが識別子を共有している場合や識別子が欠落している場合、トリガは起動しません。
  • ユーザーが遅延が経過する前に移動した場合、トリガー遅延は表示をキャンセルします。Amplitudeはトリガー時ではなく遅延後に条件付きロジックを再評価します。
  • 体験がセッション プロパティを使用する場合、設定済みのすべてのセッション プロパティ条件は表示時に一致する必要があります。

現在のページまたは画面は、Where の条件に一致していますか？

Where 設定を確認し、SDK が実際に報告する内容と照合して一致タイプをテストしてください。

ウェブ上で、クエリ パラメータや末尾のスラッシュなど、ルールを正確な URL と比較してください。 ステージング URL で機能する正規表現やパターンが、本番環境では一致しない可能性があります。

モバイルの場合、Where 条件はウェブ URL ではなくスクリーン名と一致します。「スーパーデバッガの詳細」タブの「画面」フィールドには、SDK レポートの名前が表示されます。 その文字列がインクルードルールと一致しない場合、体験は表示されません。 プロジェクト全体のデフォルトページの除外も、「プロジェクト設定」>「ガイドとサーベイ」で確認してください。プロジェクトレベルで一度設定された除外は、後で作成するものも含め、すべての体験に適用されます。 ページと画面のターゲティングはリンク共有にも適用されます。リンクはオーディエンスターゲティングを上書きしますが、場所ターゲティングを上書きしません。

ユーザーはすでにそれを見たことがありますか？

AmplitudeはデフォルトでStop showing when completedおよびStop showing when dismissedを有効にしているため、一度体験を完了または終了したユーザーは再びそれを表示することはありません。クールダウンは、期限が切れるまで表示をブロックし、エクスペリエンスをスヌーズしたユーザーは、スヌーズ期間が経過するまでそれを再び見ることはありません。ユーザーを再度資格にするには、ユーザープロフィールを開き、ガイドまたはサーベイタブに移動し、その体験の履歴を消去を選択します。

スロットルがディスプレイをブロックしていますか？

スロットリング機能は、各ユーザーが1日、1週間、1ヶ月、または1セッションで閲覧するガイドやサーベイの数に上限を設けます。また、ガイドとサーベイの設定は別々です。4 つのレイヤーすべてをチェックします。

  • グローバルな制限と期間。
  • 「間隔時間」遅延。これは、ユーザーがガイドを見た後、設定された期間、2 番目のガイドをブロックします。
  • 詳細なタグベースのスロットル機能により、最も制限が厳しい方が優位に立ちます。
  • 相互排他的グループ。グループ内の 1 つのアイテムを表示したユーザーは、他のアイテムを表示しません。

別のエクスペリエンスが既に画面に表示されていますか？

Amplitudeは一度に1つのピン、ポップオーバー、またはモーダルしか表示せず、バナーもチェックリストも1つだけ表示します。これらのフォームファクタの1つがすでに表示されており、別のフォームファクタがトリガーされている場合、2番目のフォームファクタは表示されず、キューに追加されることもありません。一度に複数の体験が対象となる場合、優先順位とタイブレーカーのルールによってどれが表示されるかが決まります。

ステップがレンダリングされるときにアンカー要素が存在しますか？

ピン、ツールチップ、カード埋め込みは、要素に添付されます。 その要素がレンダリング時にDOM（ウェブ）またはビュー階層（モバイル）に存在しない場合、ステップは表示されず、ガイドとサーベイはそのステップをスキップしたり、別の位置にフォールバックしたりすることはありません。ウェブ上では、レンダリングが遅れたり、遅延ロードされたコンポーネントの背後に存在したり、シャドウ DOM 内に存在する要素が一般的な原因です。 モバイルでは、各ターゲットビューに固有の識別子が割り当てられていること、および同じ画面上のカード埋め込みが識別子を共有していないことを確認してください。また、ピンはアニメーション化されたコンテナ内のiOSタブバー項目やビューをターゲットにすることはできません。

環境が SDK をブロックしていますか？

ウェブでは、厳格なコンテンツセキュリティポリシーが適用され、SDK が必要とするリクエストやインラインスタイルがブロックされます。 https://*.amplitude.com、script-src、connect-src、img-src、media-src、およびstyle-srcディレクティブを許可し、ポリシーがインライン スタイルをブロックしている場合は、初期化時にnonceを渡してください。ガイドとサーベイも iframe のサポートに制限があります。セレクターは iframe の境界を越えることができないため、各 iframe は何かを表示するには独自の SDK インスタンスが必要です。

モバイルでは、SDK がガイドとサーベイを取得するにはネットワーク接続が必要です。アプリの起動時にデバイスがオフラインの場合、そのセッションについては何も表示されません。 ネットワークに接続して再試行し、[スーパーデバッガのセットアップ] タブでイベント フローを確認してください。

ユーザーの SDK バージョンはこの機能をサポートしていますか？

モバイル SDK は自動更新できないため、古いバージョンを使用しているデバイスは、新しい機能に依存する体験を受け取ることができません。 たとえば、セッショントリガーの After N イベントには、iOS、Android、および React Native SDK v3.7.0 以降が必要です。この場合、このツールを使用するガイドは古いバージョンのユーザーにはまったく届きません。 モバイル SDK の変更履歴にアクセスして、バージョン要件を確認してください。

配信の失敗のように見える状況

一部の期待される動作は、正常に動作していないように感じることがあります。

プレビューモードでは動作しますが、本番環境では動作しません

プレビューモードとテストステータスはどちらも、実際のユーザーに適用されるルールを緩和します。Amplitudeはテストユーザーの制限を無視します。また、プレビューモードではスロットルを回避してトリガーイベントを手動で発行できます。これらの条件下で表示される体験は、本番環境での制限、スロットル、またはターゲティングチェックに失敗する場合があります。ウェブでは、本番ページで Chrome 拡張機能を使用して、どの条件がそれをブロックしているかを確認できます。モバイルでは、ユーザーをテストユーザーに追加し、エクスペリエンスをテストに設定することで、ライブ配信ルールで再現できます。トリガー条件、制限条件、およびスロットル条件を検査する必要がある場合は、プレビューとスーパーデバッガの詳細タブを使用します。

一部のユーザーのみがそれを見ることができます

ロールアウト率が 100% 未満であることが最も一般的な理由です。デバイス ID バケット化を使用すると、各デバイスが独立した割り当てを受け取るため、同じユーザーがあるデバイスでは資格を得ても、別のデバイスでは資格を得られない可能性があります。ログイン済みユーザーに対してデバイス間で一貫したエクスペリエンスが必要な場合はユーザー ID バケット化に切り替え、組織内の全員が同じ結果を必要としている場合はアカウント ID に切り替えます。

ユーザーは、それを閉じた後になくなったと報告しています。

アクティブなガイドは、ユーザーがそれを完了または閉じるまで、ページや画面を移動してもユーザーを追跡します。ユーザーがそれを終了した後は、デフォルトの制限値によってITが再発することはありません。そのため、誤ってその体験を終了したユーザーは、その後の訪問時に何も表示されません。その経験を履歴から消去して、再度資格を得てください。

モバイルデバイスはテストユーザーモードのままです

テストユーザーモードのままのデバイスでは、通常のユーザーと同じようにガイドとサーベイがレンダリングされません。モバイル テスターから一貫性のない動作が報告された場合は、モードがオフになっていることを確認してから、再度テストしてください。

プレビューモードではモバイルアプリは開かない

モバイルでのプレビューは、新しいブラウザタブではなく、カスタム URL スキームに依存します。 iOS に No usable data found が表示されている場合や、Android のアクションシートにアプリがリストされていない場合、OS にはプレビュー URL 用に登録されているアプリがありません。 スキャン元のデバイスにアプリをインストールし、URL スキームが「_設定」>「プロジェクト」>「一般」>「URL スキーム（モバイル）」_と一致することを確認してから、もう一度スキャンしてください。 これはターゲティングやトリガーの失敗ではありません。 OS がアプリへのリンクを渡さなかったため、SDK は実行されませんでした。

体験は一時的に非表示になります

条件付きロジックは、temporarily hide if条件が適用されている間、アクティブなガイドを非表示にすることができます。 ガイドはアクティブなままになり、これらの条件が一致しなくなったら再び表示の対象となります。 ガイドがフローの途中で消えた場合の各ステップの条件を確認してください。

グループコホートターゲティングはイベントレベルのグループを使用

計測が個々のイベントにグループプロパティを関連付けると、Amplitudeはイベントレベルのグループ化を作成します。 イベントレベルのグループは分析のために正しく機能します。グラフには正確なデータが表示され、ユーザーはグループプロファイルのユーザータブに表示されます。 ただし、イベントレベルのグループでは、ユーザーはガイド、サーベイ、または実験におけるグループコホートターゲティングの対象とはなりません。

グループコホートターゲティングを機能させるには、インストルメンテーションで各ユーザーの分析SDKのsetGroup を呼び出す必要があります。この呼び出しはユーザーのプロファイルにグループを設定し、ターゲティングはイベントレベルのグループプロパティではなく、プロファイルレベルのグループメンバーシップを評価します。

グラフとグループプロファイルデータは正しいように見えるが、ターゲットユーザーにそれでもガイドが届かない場合は、SDK 実装で setGroup を呼び出していることを確認してください。 実装の詳細については、ユーザーグループに移動してください。

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