ガイドとサーベイへのプロキシ要求

単一のAWS CloudFrontディストリビューションを設定して、静的アセットとガイドおよびサーベイのAPIトラフィックの両方をリバースプロキシします。リバースプロキシを使用すると、特定の地域でのドメインブロックや、特定の拡張機能や DNS サーバーによるドメインブロックを回避できます。ガイドとサーベイの API および静的アセットはレイテンシーに敏感であるため、Amplitude は往復時間を最小限に抑えるためにエッジホスト型ソリューションを使用することを推奨しています。

統合されたCloudFrontディストリビューションを作成する

このセットアップでは、1つのCloudFrontディストリビューションと3つのオリジンと3つのキャッシュ動作を使用します。

• デフォルトのオリジンは、静的 SDK アセットをプロキシcdn.amplitude.comしますcdn.eu.amplitude.com。
• セカンダリオリジンは、 gs.amplitude.com または gs.eu.amplitude.com で始まる API リクエストをプロキシします/sdk/。
• 第 3 のオリジンは、ワイルドカードパターンを使用してナッジ画像をプロキシengagement-static.amplitude.comしますengagement-static.eu.amplitude.com。

実装で AI アシスタントを使用している場合は、アシスタントチャットホストに 4 つ目のオリジンと動作を追加してください。 詳細については、「プロキシ AI アシスタント」を参照してください。

ステップバイステップの設定

1. AWS で、CloudFront を開き、Create CloudFront distribution をクリックします。

2. 最初のオリジンを設定します。

   • オリジンドメイン: 米国のデータセンターの場合、または EU のデータセンターcdn.eu.amplitude.comの場合cdn.amplitude.com
   • 許可されている HTTP メソッド： GET, HEAD, OPTIONS
     • HTTP メソッドをキャッシュ： OPTIONS
   • キャッシュポリシー： 静的資産に適切なキャッシュポリシーを選択します （例： CachingOptimized）。
   • オリジンリクエストポリシー： AllViewerExceptHostHeader
   • レスポンスヘッダーポリシー： CORS-with-preflight-and-SecurityHeadersPolicy
   • Web アプリケーションファイアウォール (WAF): セキュリティ保護を有効にしないでください。

   [ディストリビューションを作成] をクリックします

3. ガイドとサーベイ API 用に 2 つ目のオリジンを追加します。_オリジン_タブに移動し、オリジンを作成をクリックします。

   • オリジンのドメイン:
     • gs.amplitude.com 米国のデータセンターの場合、または
     • gs.eu.amplitude.com EUのデータセンター向け

4. 「Behaviors」タブに移動し、「Create behavior（動作を作成）」をクリックします。

   • パスパターン： /sdk/*
   • オリジン: 選択gs.amplitude.comまたは gs.eu.amplitude.com
   • 許可されている HTTP メソッド： GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE
     • HTTP メソッドをキャッシュ： OPTIONS
   • キャッシュポリシー：CachingDisabled
   • オリジンリクエストポリシー： AllViewerExceptHostHeader
   • レスポンスヘッダーポリシー： CORS-with-preflight-and-SecurityHeadersPolicy

5. ナッジ画像用に 3 番目のオリジンを追加します。_オリジン_タブに移動し、オリジンを作成をクリックします。

   • オリジンのドメイン:
     • engagement-static.amplitude.com 米国のデータセンター向け
     • engagement-static.eu.amplitude.com EUのデータセンター向け

6. 「Behaviors」タブに移動し、「Create behavior（動作を作成）」をクリックします。

   • パスパターン： *
   • オリジン: 選択engagement-static.amplitude.comまたは engagement-static.eu.amplitude.com
   • 許可されている HTTP メソッド： GET, HEAD, OPTIONS
     • HTTP メソッドをキャッシュ： OPTIONS
   • キャッシュポリシー： 静的資産に適切なキャッシュポリシーを選択します （例： CachingOptimized）。
   • オリジンリクエストポリシー： AllViewerExceptHostHeader
   • レスポンスヘッダーポリシー： CORS-with-preflight-and-SecurityHeadersPolicy

AI アシスタントをプロキシする

実装で AI アシスタントを使用している場合は、同じ CloudFront ディストリビューションに 4 つ目のオリジンと動作を追加してください。 アシスタントは、チャットトラフィックをガイドとサーベイ API ホストに送信しません。これは、/api/パスの下にある別のホストを呼び出します:

• assistant-api.amplitude.com 米国のデータセンター向けです。
• assistant-api.eu.amplitude.com EUデータセンター向けです。

開始する前に、ブラウザのネットワークタブに、houston-chat.prod.us-west-2.amplitude.com などの地域固有のホスト名へのアシスタントリクエストが表示されることがあります。 いずれにしても、assistant-api.amplitude.comまたは assistant-api.eu.amplitude.comをオリジンとして使用してください。 両方のホスト名が同じサービスに到達します。

アシスタントのオリジンと動作を追加するには:

1. AI アシスタントのオリジンを追加します。 _オリジン_タブに移動し、オリジンを作成をクリックします。

   • オリジンのドメイン:
     • assistant-api.amplitude.com 米国のデータセンター向け
     • assistant-api.eu.amplitude.com EUのデータセンター向け

2. AI アシスタントの動作を追加します。 _「動作」_タブに移動し、「動作を作成」をクリックします。

   • パスパターン： /api/*
   • オリジン: 選択assistant-api.amplitude.comまたは assistant-api.eu.amplitude.com
   • 許可されている HTTP メソッド： GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE
     • HTTP メソッドをキャッシュ： OPTIONS
   • キャッシュポリシー：CachingDisabled
   • オリジンリクエストポリシー： AllViewerExceptHostHeader
   • レスポンスヘッダーポリシー： CORS-with-preflight-and-SecurityHeadersPolicy
   • オブジェクトを自動的に圧縮： No

ワイルドカードパターンは、/api/*表示されているとおりに正確に使用してください。アシスタントは、/api/chat/ および/api/v2/chat/ の下にあるいくつかのエンドポイントを呼び出します。これには、セッションの作成、履歴、添付ファイル、ツールの承認、ストリーミングが含まれます。 個々のパスをリストする動作は、省略されたエンドポイントを破壊します。

プロキシをテストする

AWS がディストリビューションをデプロイした後、各パスをテストして、リクエストが正しいオリジンにルーティングされていることを確認してください。

ガイドとサーベイ API をテストする

<domain_name> SUBDOMAINを CloudFront ドメイン名に、<api_key> APIKEYをプロジェクトの API キーに置き換えます。

curl -i 'https://SUBDOMAIN.cloudfront.net/sdk/v1/decide' -H 'Authorization: Api-Key APIKEY'

成功した応答は HTTP ステータス 200 OKを返します。

CDN をテストする

curl -I 'https://SUBDOMAIN.cloudfront.net/engagement-browser/prod/index.min.js.gz'

成功した応答は HTTP ステータス 200 OKを返します。

AI アシスタント API をテストする

curl -i 'https://SUBDOMAIN.cloudfront.net/api/chat/settings' -H 'Authorization: Api-Key APIKEY'

成功した応答は HTTP ステータス 200 OKを返します。CloudFront からの 403<error_code> エラーは、その動作がアシスタントオリジンにルーティングされないことを/api/*意味します。

プロキシを使用して SDK を初期化する

serverUrl, cdnUrl, mediaUrl, および chatUrl を同じ CloudFront ドメインに向けます:

engagement.init("API_KEY", {
  serverUrl: "https://SUBDOMAIN.cloudfront.net",
  cdnUrl: "https://SUBDOMAIN.cloudfront.net",
  mediaUrl: "https://SUBDOMAIN.cloudfront.net",
  chatUrl: "https://SUBDOMAIN.cloudfront.net",
});

このmediaUrlパラメータにより、ナッジで使用される画像もCloudFrontディストリビューションを通じてプロキシされるようになります。このmediaUrlパラメータを使用すると、顧客ドメインが engagement-static.amplitude.com へのリクエストをブロックした場合に画像がロードされないことを防ぐことができます。

このchatUrlパラメータは、AI アシスタントのトラフィックを CloudFront ディストリビューション経由でルーティングします。 実装で AI アシスタントを使用していない場合はchatUrl省略してください。 それがない場合、SDK はアシスタント ホストを直接呼び出し、そのホストがブロックされている場合でもアシスタントは失敗します。

一般的なプロキシ問題のトラブルシューティング

• プレビューモードが機能しません
  • 症状：：プレビューモードでガイドが正しく読み込まれないか、表示されない
  • 原因: パスパターンがワイルドカードパターンの代わりに特定のパスで構成されている場合などです /sdk/*(/sdk/configを使用した場合など)。
  • 解決策: パスパターンをステップ 4 で指定したとおりに設定します。プレビューモードでは /sdk/* にリクエストを送信しますが、このリクエストは特定のパスでプロキシされません。/sdk/admin/config
• ガイドは非表示または完了状態を保持しません
  • 症状：：ユーザーがガイドを非表示または完了した後でも、次のセッションでガイドが再表示されます。
  • 原因:
    • 原因 1: 許可されている HTTP メソッドには、ガイドとサーベイで状態更新に必要な POST が含まれていません。
    • 原因2：：オリジンリクエストポリシーが AllViewerExceptHostHeader
  • ソリューション：
    • 解決策 1: ステップ 4 で許可されている HTTP メソッドが、GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE他の必須メソッドとともに次のものを含んでいることを確認しますPOST。 POSTがなければ、SDK は/stateユーザーインタラクション状態を更新するためのリクエストをエンドポイントに送信できません。
    • 解決策 2: オリジンリクエストポリシーが AllViewerExceptHostHeader であることを確認してください。POST ホストヘッダーが無効な値で上書きされている場合、リクエストは失敗します。
• 画像はナッジで読み込まれません
  • 症状：ガイド内の画像が壊れているか欠落しているように見え、代わりにプレースホルダーアイコンが表示されます
  • 原因:
    • 原因 1: mediaUrlパラメータが SDK の初期化時に設定されていません。
    • 原因 2: 画像のオリジンにワイルドカード*キャッシュの動作がない。
    • 原因3: 画像のオリジンが正しく設定されていない。
  • ソリューション：
    • 解決策 1: SDK の初期化mediaUrl: "https://SUBDOMAIN.cloudfront.net"に追加します。
    • 解決策 2: engagement-static.amplitude.comまたは engagement-static.eu.amplitude.comオリジンを指すワイルドカード*キャッシュ動作を作成済みであることを確認します。
    • 解決策3: 画像のオリジンドメインがお客様のデータセンター(米国またはEU)と一致していることを確認します。
• AI アシスタントが応答しないか、または答えが 1 つのブロックに表示される
  • 症状：チャット ウィンドウにエラーが表示されたり、空のままになったり、長い休止後に単語ごとにストリーミングされるのではなく完全な回答が表示されたりします。
  • 原因:
    • 原因 1: chatUrlは設定されていないため、SDK はアシスタント ホストを直接呼び出し、ブロックされたドメインはリクエストをドロップします。
    • 原因 2: /api/*動作が欠落しているため、アシスタントのリクエストはワイルドカード*動作に転換し、画像のオリジンに到達します。
    • 原因 3: この/api/*動作によりオブジェクトが自動的に圧縮され、ストリーミングされた応答がバッファリングされます。
  • ソリューション：
    • 解決策 1: SDK の初期化chatUrl: "https://SUBDOMAIN.cloudfront.net"に追加します。
    • 解決策 2: アシスタントのオリジンを指す/api/*動作を作成します。 CloudFront は最も具体的なパスパターンに一致するため、* よりも優先されます。/api/*
    • 解決策 3: /api/*動作でオブジェクトを自動的に圧縮をNoに設定し、そのキャッシュポリシーをCachingDisabledに設定したままにします。

一般的なデバッグ手順

1. CloudFront ログを確認する: CloudFront ディストリビューションでログを有効にすることで、どのリクエストが実行されているかとそのレスポンスコードを確認できます。

2. すべてのオリジンが設定されていることを確認します。CDN オリジン (gs.amplitude.com または gs.eu.amplitude.com)、API オリジン (cdn.amplitude.com または cdn.eu.amplitude.com)、および画像オリジン (engagement-static.amplitude.com または engagement-static.eu.amplitude.com) があることを確認します。 AI アシスタントを使用する場合は、アシスタントのオリジン (assistant-api.amplitude.com または assistant-api.eu.amplitude.com) も確認してください。

3. 各エンドポイントをテストする：「プロキシのテスト」セクションの curl コマンドを使用して、API、CDN、およびアシスタントパスが正しく動作していることを確認します。

4. ブラウザのネットワークタブを確認してください: ブラウザの開発者ツールのネットワークタブで失敗したリクエストを探してください。特に、ルーティングの問題を示す可能性のある 404 または 403 エラーを探してください。