가이드 및 설문조사에 대한 프록시 요청
리버스 프록시는 사용자가 소유한 도메인을 통해 가이드 및 설문조사 트래픽을 라우팅합니다. 광고 차단기, 브라우저 확장 프로그램, DNS 필터 또는 지역 방화벽이 Amplitude 도메인을 차단할 때 SDK는 계속 작동합니다. 하나의 프록시 호스트를 실행하고, 세 개의 경로 패턴을 세 개의 Amplitude 호스트(AI 어시스턴트를 사용하는 경우 네 proxyUrl개)로 라우팅하며, 단일 옵션으로 SDK가 해당 호스트를 가리키도록 설정합니다. 가이드 및 설문조사 API와 정적 자산은 지연 시간에 민감합니다. 가능한 경우 CDN 또는 엣지 함수와 같은 엣지 호스팅 프록시를 사용하십시오.
라우팅 작동 방식
SDK가 호출하는 모든 Amplitude 호스트는 별개의 경로를 소유하므로 하나의 프록시 호스트가 다시 작성하지 않고도 경로별로 라우팅할 수 있습니다:
| 경로 | 미국 호스트 | 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 어시스턴트를 사용하지 않는 경우 선택 사항으로 표시된 부분을 생략하십시오.
: 작업자를 생성하고, 이 스크립트를 붙여넣은 다음,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/*에 대해 최소 몇 분 동안 열린 상태로 유지되도록 허용하는지 확인하십시오. 응답을 버퍼링하는 플랫폼은 에이전트가 완료된 후 각 응답을 하나의 블록으로 제공합니다.
프록시를 사용하여 SDK 초기화
프록시 호스트로 proxyUrl설정합니다.
engagement.init("API_KEY", {
proxyUrl: "https://gs.example.com",
});
가이드 및 설문조사를 분석 브라우저 SDK 플러그인으로 설치하는 경우 플러그인에 동일한 옵션을 전달하십시오.amplitude.add(window.engagement.plugin({ proxyUrl: "https://gs.example.com" }))
proxyUrl serverUrl는 cdnUrl, mediaUrl및 chatUrl를 동일한 값으로 설정합니다. 한 유형의 트래픽을 다른 곳으로 전송하려면 해당 옵션을 명시적으로 설정하십시오. 명시적 값은 proxyUrl보다 우선합니다. chatUrl를 지원하지 않는 SDK 버전의 경우 proxyUrl, 및 serverUrl를 프록시 호스트로 대신 설정하고, AI 어시스턴트를 사용하는 경우 cdnUrl를 설정하십시오mediaUrl.
프록시 테스트
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'
Amplitude가 아닌 프록시의 A 403 또는 404 응답은 일반적으로 요청이 잘못된 규칙과 일치했음을 의미합니다.
일반적인 프록시 문제 해결
- 미리보기 모드가 작동하지 않습니다
- 증상: 미리보기 모드에서 가이드를 올바르게 로드하거나 표시하지 못함
- 원인:
/sdk/*규칙은 와일드카드 대신/sdk/v1/config와 같은 특정 경로를 나열합니다. - 해결 방법:
/sdk/*와일드카드를 사용합니다. 미리보기 모드에서/sdk/v1/preview/config를 호출합니다.
- 가이드는 닫기 또는 완료 상태를 지속적으로 유지하지 않습니다.
- 증상: 사용자가 가이드를 닫거나 완료한 후 다음 세션에서 다시 나타납니다.
- 원인:
/sdk/*규칙에서POST를 허용하지 않거나, 프록시 호스트를Host헤더로 전달합니다. - 해결 방법:
/sdk/*에GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE을(를) 허용하고 Amplitude 호스트를Host헤더로 전송합니다. CloudFront에서AllViewerExceptHostHeader오리진 요청 정책을 사용하십시오.
- 이미지가 가이드에서 로드되지 않습니다
- 증상: 이미지가 손상된 것으로 나타나거나 위치 표시자 아이콘이 표시됩니다.
- 원인: 포괄 규칙이 이미지 호스트로 라우팅되지 않거나, SDK가 미디어에 프록시를 사용하지 않습니다.
- 해결 방법:
/sdk/*,/engagement-browser/*및/api/*(있는 경우) 외부의 모든 항목을engagement-static.amplitude.com또는engagement-static.eu.amplitude.com로 라우팅하고proxyUrl또는mediaUrl로 설정합니다.
- AI 비서가 응답하지 않거나 답변이 한 블록에 나타납니다.
- 증상: 채팅 창에 오류가 표시되거나, 비어 있는 상태로 유지되거나, 오랜 시간 동안 일시 중지한 후 단어별로 스트리밍되는 대신 전체 답변이 표시됩니다.
- 원인:
/api/*규칙이 누락되어 어시스턴트 요청이 이미지 호스트에 도달하거나, 프록시가 스트리밍된 응답을 버퍼링 또는 압축합니다. - 해결 방법:
/api/*규칙을 추가하고 버퍼링 및 압축을 끕니다. CloudFront에서 자동으로 객체 압축을No로 설정합니다. NGINX에서proxy_buffering off를 설정합니다.
- SDK가 로드되지 않습니다.
- 증상: 브라우저 콘솔에서 Engagement SDK 번들이 로드되지 않았다고 보고합니다.
- 원인:
/engagement-browser/*규칙이 누락되었거나 잘못된 호스트로 라우팅됩니다. - 해결 방법:
/engagement-browser/*를cdn.amplitude.com또는cdn.eu.amplitude.com로 라우팅한 다음 SDK 번들 테스트를 실행합니다.
다른 오류가 발생한 경우 브라우저의 개발자 도구를 열고 네트워크 탭을 프록시 호스트별로 필터링한 다음 어떤 요청이 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.