Proxy requests to Guides and Surveys

Set up a single AWS CloudFront distribution to reverse proxy both static assets and Guides and Surveys API traffic. A reverse proxy can help circumvent domain blocking in certain regions or by specific extensions and DNS servers. Guides and Surveys APIs and static assets are latency-sensitive, so Amplitude recommends using edge-hosted solutions to minimize round-trip time.

Create a unified CloudFront distribution

This setup uses one CloudFront distribution with three origins and three cache behaviors:

• The default origin proxies cdn.amplitude.com or cdn.eu.amplitude.com for static SDK assets.
• A secondary origin proxies gs.amplitude.com or gs.eu.amplitude.com for API requests prefixed with /sdk/.
• A third origin proxies engagement-static.amplitude.com or engagement-static.eu.amplitude.com for nudge images using a wildcard pattern.

If your implementation uses the AI assistant, add a fourth origin and behavior for the assistant chat host. Go to Proxy the AI assistant for details.

Step-by-step configuration

1. In AWS, open CloudFront and click Create CloudFront distribution.

2. Configure the first origin:

   • Origin domain: cdn.amplitude.com for the US data center, or cdn.eu.amplitude.com for the EU data center
   • Allowed HTTP methods: GET, HEAD, OPTIONS
     • Cache HTTP methods: OPTIONS
   • Cache policy: Choose a suitable caching policy for static assets (for example, CachingOptimized)
   • Origin request policy: AllViewerExceptHostHeader
   • Response headers policy: CORS-with-preflight-and-SecurityHeadersPolicy
   • Web Application Firewall (WAF): Don't enable security protections.

   Click Create distribution

3. Add a second origin for the Guides and Surveys API. Navigate to the Origins tab and click Create origin:

   • Origin domain:
     • gs.amplitude.com for the US data center, or
     • gs.eu.amplitude.com for the EU data center

4. Navigate to the 'Behaviors' tab and click Create behavior:

   • Path pattern: /sdk/*
   • Origin: Select gs.amplitude.com or gs.eu.amplitude.com
   • Allowed HTTP methods: GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE
     • Cache HTTP methods: OPTIONS
   • Cache policy: CachingDisabled
   • Origin request policy: AllViewerExceptHostHeader
   • Response headers policy: CORS-with-preflight-and-SecurityHeadersPolicy

5. Add a third origin for nudge images. Navigate to the Origins tab and click Create origin:

   • Origin domain:
     • engagement-static.amplitude.com for the US data center
     • engagement-static.eu.amplitude.com for the EU data center

6. Navigate to the 'Behaviors' tab and click Create behavior:

   • Path pattern: *
   • Origin: Select engagement-static.amplitude.com or engagement-static.eu.amplitude.com
   • Allowed HTTP methods: GET, HEAD, OPTIONS
     • Cache HTTP methods: OPTIONS
   • Cache policy: Choose a suitable caching policy for static assets (for example, CachingOptimized)
   • Origin request policy: AllViewerExceptHostHeader
   • Response headers policy: CORS-with-preflight-and-SecurityHeadersPolicy

Proxy the AI assistant

If your implementation uses the AI assistant, add a fourth origin and behavior to the same CloudFront distribution. The assistant doesn't send its chat traffic to the Guides and Surveys API host. It calls a separate host under the /api/ path:

• assistant-api.amplitude.com for the US data center.
• assistant-api.eu.amplitude.com for the EU data center.

Before you start, your browser's network tab may show assistant requests going to a region-specific hostname such as houston-chat.prod.us-west-2.amplitude.com. Use assistant-api.amplitude.com or assistant-api.eu.amplitude.com as the origin anyway. Both hostnames reach the same service.

To add the assistant origin and behavior:

1. Add an origin for the AI assistant. Navigate to the Origins tab and click Create origin:

   • Origin domain:
     • assistant-api.amplitude.com for the US data center
     • assistant-api.eu.amplitude.com for the EU data center

2. Add a behavior for the AI assistant. Navigate to the Behaviors tab and click Create behavior:

   • Path pattern: /api/*
   • Origin: Select assistant-api.amplitude.com or assistant-api.eu.amplitude.com
   • Allowed HTTP methods: GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE
     • Cache HTTP methods: OPTIONS
   • Cache policy: CachingDisabled
   • Origin request policy: AllViewerExceptHostHeader
   • Response headers policy: CORS-with-preflight-and-SecurityHeadersPolicy
   • Compress objects automatically: No

Use the wildcard pattern /api/* exactly as shown. The assistant calls several endpoints under /api/chat/ and /api/v2/chat/, including session creation, history, attachments, tool approval, and streaming. A behavior that lists individual paths breaks the endpoints it omits.

Test the proxy

After AWS deploys the distribution, test each path to confirm that requests route to the correct origins.

Test the Guides and Surveys API

Replace SUBDOMAIN with the CloudFront domain name and APIKEY with your project’s API key.

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

A successful response returns HTTP status 200 OK.

Test the CDN

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

A successful response returns HTTP status 200 OK.

Test the AI assistant API

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

A successful response returns HTTP status 200 OK. A 403 error from CloudFront means the /api/* behavior doesn't route to the assistant origin.

Initialize the SDK with the proxy

Point serverUrl, cdnUrl, mediaUrl, and chatUrl to the same CloudFront domain:

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

The mediaUrl parameter ensures that images used in nudges are also proxied through your CloudFront distribution. The mediaUrl parameter prevents images from failing to load when customer domains block requests to engagement-static.amplitude.com.

The chatUrl parameter routes AI assistant traffic through your CloudFront distribution. Omit chatUrl if your implementation doesn't use the AI assistant. Without it, the SDK calls the assistant host directly, and the assistant fails wherever that host is blocked.

Troubleshooting common proxy issues

• Preview mode doesn't work
  • Symptoms: Preview mode fails to load or display guides properly
  • Cause: Path pattern configured with specific paths instead of wildcard pattern /sdk/* (for example, using /sdk/config)
  • Solution: Set the path pattern to /sdk/* exactly as specified in step 4. Preview mode makes requests to /sdk/admin/config, which won't be proxied with specific paths.
• Guides don't persist dismissal or completion state
  • Symptoms: Guides reappear on the next session even after the user dismisses or completes them.
  • Cause:
    • Cause 1: Allowed HTTP methods don't include POST, which Guides and Surveys requires for state updates.
    • Cause 2: the origin request policy isn't AllViewerExceptHostHeader
  • Solution:
    • Solution 1: Verify that allowed HTTP methods in step 4 include POST along with other required methods: GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE. Without POST, the SDK can't send requests to the /state endpoint to update user interaction state.
    • Solution 2: Confirm the origin request policy is AllViewerExceptHostHeader. POST requests fail if the host header is overridden with an invalid value.
• Images don't load in nudges
  • Symptoms: Images in guides appear as broken or missing, showing placeholder icons instead
  • Cause:
    • Cause 1: mediaUrl parameter not configured in SDK initialization.
    • Cause 2: Missing wildcard * cache behavior for image origin.
    • Cause 3: Image origin not configured correctly.
  • Solution:
    • Solution 1: Add mediaUrl: "https://SUBDOMAIN.cloudfront.net" to your SDK initialization.
    • Solution 2: Confirm you have created a wildcard * cache behavior pointing to the engagement-static.amplitude.com or engagement-static.eu.amplitude.com origin.
    • Solution 3: Verify the image origin domain matches your data center (US or EU).
• The AI assistant doesn't answer, or the answer appears in one block
  • Symptoms: The chat window shows an error, stays empty, or displays the full answer after a long pause instead of streaming it word by word.
  • Cause:
    • Cause 1: chatUrl isn't configured, so the SDK calls the assistant host directly and a blocked domain drops the request.
    • Cause 2: The /api/* behavior is missing, so assistant requests fall through to the wildcard * behavior and reach the image origin.
    • Cause 3: The /api/* behavior compresses objects automatically, which buffers the streamed response.
  • Solution:
    • Solution 1: Add chatUrl: "https://SUBDOMAIN.cloudfront.net" to your SDK initialization.
    • Solution 2: Create the /api/* behavior pointing to the assistant origin. CloudFront matches the most specific path pattern, so /api/* takes precedence over *.
    • Solution 3: Set Compress objects automatically to No on the /api/* behavior and keep its cache policy set to CachingDisabled.

General debugging steps

1. Check CloudFront logs: Enable logging on your CloudFront distribution to see which requests are being made and their response codes.

2. Verify all origins are configured: Confirm that you have the CDN origin (cdn.amplitude.com or cdn.eu.amplitude.com), the API origin (gs.amplitude.com or gs.eu.amplitude.com), and the image origin (engagement-static.amplitude.com or engagement-static.eu.amplitude.com). If you use the AI assistant, confirm the assistant origin (assistant-api.amplitude.com or assistant-api.eu.amplitude.com) as well.

3. Test each endpoint: Use the curl commands in the "Test the proxy" section to verify that the API, CDN, and assistant paths work correctly.

4. Check browser network tab: Look for failed requests in your browser's developer tools network tab, particularly 404 or 403 errors that may indicate routing issues.