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

リバースプロキシは、所有するドメインを通じてガイドとサーベイのトラフィックをルーティングします。 SDKは、広告ブロッカー、ブラウザ拡張機能、DNSフィルタ、または地域ファイアウォールがAmplitudeドメインをブロックしている場合でも、機能し続けます。 1つのプロキシホストを実行し、3つのパスパターンを3つのAmplitudeホスト(AIアシスタントを使用している場合は4つ)にルーティングし、SDKを単一のproxyUrlオプションでそのホストに指定します。ガイドとサーベイAPIと静的アセットは遅延に敏感です。可能であれば、CDNやedge関数などのエッジホスト型プロキシを使用してください。

ルーティングの仕組み

SDKが呼び出すすべてのAmplitudeホストは異なるパスを所有しているため、1つのプロキシホストは書き換えなくてもパスごとにルーティングできます。

この/api/*ルールは、AIアシスタントを使用する場合にのみ必要です。この設定がない場合、ガイド、サーベイ、リソースセンターはプロキシを通じて正常に機能します。

各ルールは次のことを行う必要があります。

  • フルパスとクエリ文字列を変更せずに転送します。
  • プロキシホストではなく、AmplitudeホストをHostヘッダーとして送信します。
  • GET、HEAD、OPTIONS、PUT、POST、PATCH、およびDELETEを/sdk/*および/api/*上で許可します。SDKはPOSTを使用して、非表示状態と完了状態を保存します。
  • /api/*ルールを追加した場合、そのレスポンスをバッファリングしたり圧縮したりせずにストリーミングします。AIアシスタントは、長期間続くPOSTリクエストに対して、各応答をサーバーから送信されたイベントとしてストリーミングします。

ワイルドカードパターンを、表示されているとおりに使用してください。/sdk/v1/configのように個々のパスをリストしないでください。SDKは、プレビューモードを含め、各プレフィックスの下で多くのエンドポイントを呼び出します。/sdk/v1/preview/config特定のパスをリストするルールは、省略されたエンドポイントを破壊します。

プロキシホストを選択する

このプロキシは、専用のサブドメインから、またはアプリのドメイン上のパスから提供できます。

  • 専用サブドメイン:たとえば、https://gs.example.com。このルールは、サブドメインのルートに適用されます。 これをCloudflare Workers、CloudFront、またはNGINXで使用してください。
  • アプリのドメイン上のパス:例、https://app.example.com/gs。各ルールは、受信パスに/gsプレフィックスを追加し、転送前にそれを削除します。これを Next.jsやVercelなどのフレームワークの書き換えで使用してください。これらの場合、ルートパスがアプリ自身のルートと衝突します。

中立的な名前を選択します。 広告ブロッカーは、ホスト名やパスに含まれるanalytics、tracking、telemetry、またはamplitudeといった単語と一致することがよくあります。

プロキシを設定する

この例では、米国のホストを使用しています。 EUデータセンターの場合は、各ホストをルーティングテーブルからEU対応のホストに置き換えます。 AIアシスタントを使用しない場合は、オプションとしてマークされている部分を省略してください。

でワーカーを作成し、このスクリプトを貼り付けてから、設定 > Domains & Routes で gs.example.com のようなカスタムドメインを割り当てます。

js
const UPSTREAMS = {
  sdk: "https://gs.amplitude.com",
  cdn: "https://cdn.amplitude.com",
  media: "https://engagement-static.amplitude.com",
  // Optional: only needed for the AI assistant
  api: "https://assistant-api.amplitude.com",
};
function upstreamFor(pathname) {
  if (pathname.startsWith("/sdk/")) return UPSTREAMS.sdk;
  if (pathname.startsWith("/engagement-browser/")) return UPSTREAMS.cdn;
  // Optional: only needed for the AI assistant
  if (pathname.startsWith("/api/")) return UPSTREAMS.api;
  return UPSTREAMS.media;
}
export default {
  async fetch(request) {
    const url = new URL(request.url);
    const target = new URL(
      url.pathname + url.search,
      upstreamFor(url.pathname),
    );
    return fetch(new Request(target, request));
  },
};

あなたのproxyUrlはhttps://gs.example.comです。

AIアシスタントを使用している場合は、プラットフォームがレスポンスをストリーミングし、リクエストを /api/*で少なくとも数分間維持できることを確認してください。レスポンスをバッファリングするプラットフォームは、エージェントの終了後に各回答を1つのブロックで配信します。

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

proxyUrl をプロキシホストに設定します:

js
engagement.init("API_KEY", {
  proxyUrl: "https://gs.example.com",
});

ガイドとサーベイを分析Browser SDKプラグインとしてインストールした場合、同じオプションをプラグインに渡しますamplitude.add(window.engagement.plugin({ proxyUrl: "https://gs.example.com" }))。

proxyUrlは、serverUrl、cdnUrl、mediaUrlおよびchatUrlを同じ値に設定します。あるタイプのトラフィックを別の場所に送信するには、そのオプションを明示的に設定します。明示的な値は proxyUrl よりも優先されます。proxyUrlをサポートしていないSDKバージョンでは、serverUrl、cdnUrl、およびmediaUrlにプロキシホストを設定し、AIアシスタントを使用している場合はchatUrlも設定してください。

プロキシをテストする

PROXY_URL を proxyUrl に、APIKEY をプロジェクトのAPIキーに置き換えてください。各リクエストは、プロキシが正しくルーティングした場合にHTTPステータス200 OKを返します。

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

bash
curl -i 'PROXY_URL/sdk/v1/decide' -H 'Authorization: Api-Key APIKEY'

SDKバンドルをテストします:

bash
curl -I 'PROXY_URL/engagement-browser/prod/index.min.js.gz'

AI アシスタントを使用している場合は、アシスタント API をテストします。

bash
curl -i 'PROXY_URL/api/chat/settings' -H 'Authorization: Api-Key APIKEY'

プロキシからの403または404レスポンスは、Amplitudeからではなく、通常はリクエストが間違ったルールに一致したことを意味します。

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

  • プレビューモードが機能しません
    • 症状:プレビューモードでガイドが正しく読み込まれないか、表示されません。
    • 原因: この/sdk/*ルールでは、ワイルドカードの代わりに/sdk/v1/configのような特定のパスがリストされます。
    • 解決策:/sdk/*ワイルドカードを使用します。プレビューモードは/sdk/v1/preview/configを呼び出します。
  • ガイドは非表示または完了状態を保持しません
    • 症状:ユーザーがガイドを非表示または完了した後、次のセッションでガイドが再表示されます。
    • 原因: /sdk/*ルールはPOSTを許可していないか、プロキシホストをHostヘッダーとして転送しています。
    • 解決策:GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETEを/sdk/*で許可し、AmplitudeホストをHostヘッダーとして送信します。CloudFrontでは、AllViewerExceptHostHeaderオリジンリクエストポリシーを使用します。
  • 画像はガイドに読み込まれません
    • 症状:画像が壊れているように見えるか、プレースホルダーアイコンが表示されます。
    • 原因:catch-allルールが画像ホストにルーティングされない、またはSDKがメディアにプロキシを使用していない、という状態。
    • 解決策:/sdk/*、/engagement-browser/*、および/api/*(存在する場合)以外のすべてをengagement-static.amplitude.comまたはengagement-static.eu.amplitude.comへルーティングし、proxyUrlまたはmediaUrlを設定します。
  • AI アシスタントが応答しないか、または答えが 1 つのブロックに表示される
    • 症状:チャット ウィンドウにエラーが表示されたり、空のままになったり、長い休止後に単語ごとにストリーミングされるのではなく完全な回答が表示されたりします。
    • 原因:/api/*ルールが欠落しているため、アシスタントのリクエストが画像ホストに到達するか、プロキシがストリーミングされたレスポンスをバッファリングまたは圧縮します。
    • 解決策: /api/*ルールを追加し、そのルールのバッファリングと圧縮をオフにします。 CloudFrontで、Compress objects automatically をNoに設定します。NGINXでproxy_buffering offを設定します。
  • SDKがロードされません
    • 症状:ブラウザのコンソールは、Engagement SDKバンドルがロードされなかったことを報告します。
    • 原因:/engagement-browser/*ルールが欠落しているか、間違ったホストにルーティングされています。
    • 解決策:/engagement-browser/*へcdn.amplitude.comまたはcdn.eu.amplitude.comをルーティングしてから、SDK bundle testを実行します。

その他のエラーが発生した場合は、ブラウザの開発者ツールを開き、_ネットワーク_タブをプロキシホストでフィルタリングし、どのリクエストが403、404またはCORSエラーを返しているかを確認してください。障害のある各パスをルーティングテーブルと比較します。

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

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.

このページでは