Set up a single AWS CloudFront distribution to reverse proxy both static assets and Guides and Surveys API traffic. This may help circumvent domain blocking in certain regions or by specific extensions and DNS servers. Guides and Surveys APIs and static assets are latency-sensitive, as a result Amplitude recommends using edge-hosted solutions to minimize round-trip time.
This setup uses one CloudFront distribution with two origins and two cache behaviors:
cdn.amplitude.com
or cdn.eu.amplitude.com
for static SDK assets.gs.amplitude.com
or gs.eu.amplitude.com
for API requests prefixed with /sdk/
.In AWS, open CloudFront and click Create CloudFront distribution.
Configure the first origin:
cdn.amplitude.com
for the US data center, or cdn.eu.amplitude.com
for the EU data centerGET, HEAD, OPTIONS
OPTIONS
CachingOptimized
)AllViewerExceptHostHeader
CORS-with-preflight-and-SecurityHeadersPolicy
Click Create distribution
Add a second origin for the Guides and Surveys API. Navigate to the Origins tab and click Create origin:
gs.amplitude.com
for the US data center, orgs.eu.amplitude.com
for the EU data centerNavigate to the 'Behaviors' tab and click Create behavior:
/sdk/*
gs.amplitude.com
or gs.eu.amplitude.com
GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE
OPTIONS
CachingDisabled
AllViewerExceptHostHeader
CORS-with-preflight-and-SecurityHeadersPolicy
/sdk/*
exactly as shown. Don't hard code a list of specific paths like /sdk/config
. The Guides and Surveys SDK makes requests to multiple endpoints under the /sdk/
path, including /sdk/admin/config
for preview mode functionality. Using specific paths instead of the wildcard pattern causes some features to fail.After AWS deploys the distribution, test both the API and CDN paths to ensure that requests route to the correct origins.
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
.
curl -I 'https://SUBDOMAIN.cloudfront.net/engagement-browser/prod/index.min.js.gz'
A successful response returns HTTP status 200 OK
.
Point both serverUrl
and cdnUrl
to the same CloudFront domain:
engagement.init("API_KEY", {
serverUrl: "https://SUBDOMAIN.cloudfront.net",
cdnUrl: "https://SUBDOMAIN.cloudfront.net"
});
Issue | Symptoms | Cause | Solution |
---|---|---|---|
Preview mode doesn't work | Preview mode fails to load or display guides properly | Path pattern configured with specific paths instead of wildcard pattern /sdk/* (for example, using /sdk/config ) |
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 | Guides reappear on the next session even after being dismissed or completed | Allowed HTTP methods don't include POST , which is required for state updates |
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 /state endpoint to update user interaction state. |
Check CloudFront logs: Enable logging on your CloudFront distribution to see which requests are being made and their response codes.
Verify both origins are configured: Ensure you have both the CDN origin (cdn.amplitude.com
or cdn.eu.amplitude.com
) and the API origin (gs.amplitude.com
or gs.eu.amplitude.com
).
Test both endpoints: Use the curl commands in the "Test the proxy" section to verify both the API and CDN paths are working correctly.
Check browser network tab: Look for failed requests in your browser's developer tools network tab, particularly 404 or 403 errors that might indicate routing issues.
August 5th, 2025
Need help? Contact Support
Visit Amplitude.com
Have a look at the Amplitude Blog
Learn more at Amplitude Academy
© 2025 Amplitude, Inc. All rights reserved. Amplitude is a registered trademark of Amplitude, Inc.