ガイドとサーベイへのプロキシ要求
リバースプロキシは、所有するドメインを通じてガイドとサーベイのトラフィックをルーティングします。 SDKは、広告ブロッカー、ブラウザ拡張機能、DNSフィルタ、または地域ファイアウォールがAmplitudeドメインをブロックしている場合でも、機能し続けます。 1つのプロキシホストを実行し、3つのパスパターンを3つのAmplitudeホスト(AIアシスタントを使用している場合は4つ)にルーティングし、SDKを単一のproxyUrlオプションでそのホストに指定します。ガイドとサーベイAPIと静的アセットは遅延に敏感です。可能であれば、CDNやedge関数などのエッジホスト型プロキシを使用してください。
ルーティングの仕組み
SDKが呼び出すすべてのAmplitudeホストは異なるパスを所有しているため、1つのプロキシホストは書き換えなくてもパスごとにルーティングできます。
| パス | 米国のホスト | EUホスト | 用途: |
|---|---|---|---|
/sdk/* | gs.amplitude.com | gs.eu.amplitude.com | ガイドとサーベイAPI(プレビューモードを含む) |
/engagement-browser/* | cdn.amplitude.com | cdn.eu.amplitude.com | SDKバンドル |
/api/*(オプション) | assistant-api.amplitude.com | assistant-api.eu.amplitude.com | AIアシスタントチャット |
| その他すべて | engagement-static.amplitude.com | engagement-static.eu.amplitude.com | ガイドとサーベイの画像 |
この/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 のようなカスタムドメインを割り当てます。
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 をプロキシホストに設定します:
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 をテストする
curl -i 'PROXY_URL/sdk/v1/decide' -H 'Authorization: Api-Key APIKEY'
SDKバンドルをテストします:
curl -I 'PROXY_URL/engagement-browser/prod/index.min.js.gz'
AI アシスタントを使用している場合は、アシスタント API をテストします。
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.