이 페이지에서

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.

가이드 및 설문조사에 대한 프록시 요청

단일 AWS CloudFront 배포를 설정하여 정적 에셋과 가이드 및 설문조사 API 트래픽을 모두 리버스 프록시합니다. 역방향 프록시는 특정 지역이나 특정 확장명과 DNS 서버에 의한 도메인 차단을 우회하는 데 도움이 될 수 있습니다. 가이드 및 설문조사 API와 정적 자산은 지연 시간에 민감하므로 Amplitude는 왕복 시간을 최소화하기 위해 엣지 호스팅 솔루션을 사용할 것을 권장합니다.

통합 CloudFront 배포 생성

이 설정은 세 개의 오리진과 세 개의 캐시 동작을 가진 하나의 CloudFront 배포를 사용합니다.

  • 기본 오리진은 정적 SDK 에셋을 위해 cdn.amplitude.com또는 cdn.eu.amplitude.com를 프록시합니다.
  • 보조 오리진은 접두사가 /sdk/인 API 요청을 위해 gs.amplitude.com또는 gs.eu.amplitude.com를 프록시합니다.
  • 세 번째 오리진은 engagement-static.amplitude.com와일드카드 패턴을 사용하여 너지 이미지를 프록시하거나 engagement-static.eu.amplitude.com제공합니다.

구현에서 AI 어시스턴트를 사용하는 경우 어시스턴트 채팅 호스트에 대한 네 번째 오리진과 동작을 추가하십시오. 자세한 내용은 AI 어시스턴트 프록시로 이동하세요.

단계별 구성

  1. AWS에서 CloudFront를 열고 Create CloudFront distribution을 클릭합니다.

  2. 첫 번째 원본을 구성합니다.

    • 출처 도메인cdn.amplitude.com: 미국 데이터 센터의 경우 cdn.eu.amplitude.com또는 EU 데이터 센터의 경우
    • 허용되는 HTTP 메소드: GET, HEAD, OPTIONS
      • HTTP 메소드 캐시: OPTIONS
    • 캐시 정책: 정적 자산에 적합한 캐시 정책을 선택합니다(예: CachingOptimized).
    • 출처 요청 정책: AllViewerExceptHostHeader
    • 응답 헤더 정책: CORS-with-preflight-and-SecurityHeadersPolicy
    • 웹 응용 프로그램 방화벽(WAF): 보안 보호를 활성화하지 마십시오.

    배포 생성을 클릭합니다.

  3. 가이드 및 설문조사 API에 대한 두 번째 오리진을 추가합니다. 원본 탭으로 이동한 후 원본 만들기를 클릭합니다.

    • 오리진 도메인:
      • gs.amplitude.com 미국 데이터 센터의 경우 또는
      • gs.eu.amplitude.com EU 데이터 센터의 경우

  4. '동작' 탭으로 이동하여 동작 만들기를 클릭합니다.

    • 경로 패턴: /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

와일드카드 패턴 /sdk/*을(를) 표시된 대로 정확하게 사용하십시오. /sdk/config와 같이 특정 경로 목록을 하드 코딩하지 마십시오. 가이드 및 설문조사 SDK는 /sdk/미리보기 모드 기능을 포함하여 /sdk/admin/config경로 아래의 여러 엔드포인트에 요청을 보냅니다. 와일드카드 패턴 대신 특정 경로를 사용하면 일부 기능이 실패할 수 있습니다.

  1. 너지 이미지에 대한 세 번째 오리진을 추가합니다. 원본 탭으로 이동한 후 원본 만들기를 클릭합니다.

    • 오리진 도메인:
      • engagement-static.amplitude.com 미국 데이터 센터의 경우
      • engagement-static.eu.amplitude.com EU 데이터 센터의 경우

  2. '동작' 탭으로 이동하여 동작 만들기를 클릭합니다.

    • 경로 패턴: *
    • 출처: 선택 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 배포에 네 번째 오리진과 동작을 추가하십시오. 도우미는 채팅 트래픽을 가이드 및 설문조사 API 호스트로 전송하지 않습니다. /api/경로 아래에 별도의 호스트를 호출합니다.

  • assistant-api.amplitude.com 미국 데이터 센터의 경우.
  • assistant-api.eu.amplitude.com EU 데이터 센터의 경우.

구현에서 AI 어시스턴트를 사용하지 않는 경우 이 섹션을 건너뛰십시오.

시작하기 전에 브라우저의 네트워크 탭에 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/*동작에서 객체 자동 압축을 끕니다. 어시스턴트는 수명이 긴 POST 요청을 통해 각 응답을 서버에서 전송한 이벤트로 스트리밍합니다. CloudFront가 응답을 압축할 때 전체 스트림을 버퍼링하므로 에이전트가 완료된 후 응답이 한 블록 내에 도착하거나 어떤 작업이 렌더링되기 전에 요청이 시간 초과됩니다.

/api/*와일드카드 패턴을 그림과 같이 정확하게 사용하십시오. 이 도우미는 세션 생성, 기록, 첨부 파일, 도구 승인 및 스트리밍을 포함하여 /api/chat/및 /api/v2/chat/아래의 여러 엔드포인트를 호출합니다. 개별 경로를 나열하는 동작은 생략된 엔드포인트를 중단시킵니다.

프록시 테스트

AWS가 배포를 완료한 후 각 경로를 테스트하여 요청이 올바른 오리진으로 라우팅되는지 확인하십시오.

가이드 및 설문조사 API 테스트

CloudFront 도메인 이름으로 SUBDOMAIN대체하고 프로젝트의 API 키로 APIKEY대체하십시오.

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

성공적인 응답은 HTTP 상태 200 OK를 반환합니다.

CDN 테스트

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

성공적인 응답은 HTTP 상태 200 OK를 반환합니다.

AI 비서 API 테스트

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

성공적인 응답은 HTTP 상태 200 OK를 반환합니다. CloudFront의 403오류는 해당 동작이 어시스턴트 오리진으로 라우팅되지 않음을 /api/*의미합니다.

프록시를 사용하여 SDK 초기화

serverUrl, cdnUrl, mediaUrl, 및 chatUrl을 동일한 CloudFront 도메인으로 지정하십시오.

js
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/config와일드카드 패턴 대신 특정 경로로 구성된 경로 패턴(예: /sdk/*를 사용함)
    • 해결 방법: 경로 패턴을 4단계에서 지정한 대로 정확하게 설정하십시오. 미리 보기 모드는 /sdk/*에 대한 요청을 생성하며, /sdk/admin/config이 요청은 특정 경로로 프록시되지 않습니다.
  • 가이드는 닫기 또는 완료 상태를 지속적으로 유지하지 않습니다.
    • 증상: 사용자가 가이드를 닫거나 완료한 후에도 다음 세션에 다시 나타납니다.
    • 원인:
      • 원인 1: 허용된 HTTP 메소드에는 가이드 및 설문조사에서 상태 업데이트를 위해 필요한 POST 이 포함되어 있지 않습니다.
      • 원인 2: 원본 요청 정책이 AllViewerExceptHostHeader 이(가) 아닙니다
    • 솔루션:
      • 해결 방법 1: GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE4단계에서 허용된 HTTP 메소드가 다른 필수 메소드와 함께 POST다음을 포함하는지 확인합니다. POST이 없으면 SDK는 사용자 상호 작용 상태를 업데이트하기 위해 /state엔드포인트에 요청을 전송할 수 없습니다.
      • 해결 방법 2: 원본 요청 정책이 AllViewerExceptHostHeader인지 확인하십시오. POST호스트 헤더가 잘못된 값으로 재정의되면 요청이 실패합니다.
  • Nudge에서 이미지가 로드되지 않습니다
    • 증상: 가이드의 이미지가 손상되거나 누락된 것으로 나타나며 대신 위치 표시자 아이콘이 표시됨
    • 원인:
      • 원인 1: mediaUrlSDK 초기화 시 매개 변수가 구성되지 않았습니다.
      • 원인 2: 이미지 출처에 대한 와일드카드 * 캐시 동작이 누락되었습니다.
      • 원인 3: 이미지 출처가 올바르게 구성되지 않았습니다.
    • 솔루션:
      • 해결 방법 1: SDK 초기화mediaUrl: "https://SUBDOMAIN.cloudfront.net"에 추가하십시오.
      • 해결 방법 2: 또는 engagement-static.amplitude.com 원본을 가리키는 engagement-static.eu.amplitude.com와일드카드 * 캐시 동작을 생성했는지 확인하십시오.
      • 해결 방법 3: 이미지 출처 도메인이 데이터 센터(미국 또는 EU)와 일치하는지 확인하십시오.
  • AI 비서가 응답하지 않거나 답변이 한 블록에 나타납니다.
    • 증상: 채팅 창에 오류가 표시되거나, 비어 있는 상태로 유지되거나, 오랜 시간 동안 일시 중지한 후 단어별로 스트리밍되는 대신 전체 답변이 표시됩니다.
    • 원인:
      • 원인 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 출처(cdn.amplitude.com 또는 cdn.eu.amplitude.com), API 출처(gs.amplitude.com 또는 gs.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 오류를 확인하세요.

이 내용이 도움이 되었나요?