Serve JavaScript SDK on Custom Domains

Use your own domain to serve the RudderStack JavaScript SDK and send events to the data plane.

This guide covers the steps to use your own domain instead of RudderStack domains for:

  • Serving the JavaScript SDK
  • Source configuration response, and
  • Sending events to the data plane.

Setting up custom domains for these use cases can help you adhere to your Content Security Policy (CSP), reduce the impact of adblockers, and satisfy any compliance-related requirements.

info

Note that:

  • You will need access to your domain’s DNS settings as well as your CDN settings.
  • The examples in this guide use AWS CloudFront. However, the settings should be similar regardless of your CDN.

Domains

The following table lists the three domains that you need to proxy via your own CDN to successfully load the SDK and route the events to the data plane.

DomainUse case
cdn.rudderlabs.comTo load the JavaScript SDK.
api.rudderstack.comTo fetch the source configuration based on the source write key.
DATA_PLANE_URLTo send events to RudderStack. See Glossary for more information on obtaining your data plane URL.
warning
To use your own domain for these endpoints, you will need to route the traffic through your CDN for which you will incur charges.

For each endpoint, you will need to create a CDN distribution and add a CNAME record in your domain for the distribution domain. This guide shows you how to do that.

Setup overview

Start by creating a new distribution. To do so, follow these steps:

  1. Log in to your AWS console.
  2. Click Services and go to Network & Content Delivery > CloudFront.
  3. Click Create a CloudFront distribution.

The following table gives a high-level overview of the required cache policy, origin request policy, and response headers policy. For detailed distribution settings, click the specific scenario.

ScenarioCache policyOrigin request policyResponse headers policy (optional)
Serving the SDKCachingOptimizedSee Origin request policy settings.None
Serving the source configurationSee Cache policy settings.See Origin request policy settings.CORS-With-Preflight
Sending events to data planeCachingDisabledSee Origin request policy settings.CORS-With-Preflight

Setup for serving SDK

Step 1: Configure distribution

The following sections highlight the required distribution settings for serving the SDK.

Origin

Custom domains distribution settings

The following table summarizes the settings:

FieldSetting
Origin domaincdn.rudderlabs.com
ProtocolHTTPS Only
HTTPS port443
Minimum origin SSL protocolTLSv1.2
Namecdn.rudderlabs.com
Enable Origin ShieldNo

Default cache behavior settings

Custom domains distribution settings

The following table summarizes the settings:

FieldSetting
Compress objects automaticallyYes
Viewer protocol policyRedirect HTTP to HTTPS
Allowed HTTP methodsGET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE
Restrict viewer accessNo

Cache key and origin requests

Select Cache policy and origin request policy (recommended) and configure the following settings:

Custom domains distribution settings

The following table summarizes the settings:

FieldSetting
Cache policyCachingOptimized
Origin request policySee Origin request policy settings.
Response headers policyNone
Origin request policy settings

Create a new origin request policy with the following settings:

Origin request policy settings
FieldSetting
Namerudderstack-allow-headers
HeadersInclude the following headers
Add header
  • Access-Control-Request-Headers
  • Access-Control-Request-Method
  • Origin
  • Content-Encoding
Query stringsAll
CookiesNone

Additional distribution settings

Custom domains distribution settings

The following table summarizes the settings:

FieldSetting
Price classUse all edge locations(best performance)
Alternate domain name(CNAME)<YOUR_CUSTOM_DOMAIN>
SSL CertificateAdd your custom SSL Certificate. See Use custom SSL certificates for more information.
Supported HTTP versionsHTTP/2
Standard loggingOff
IPv6On

Step 2: Deploy distribution

Click Create distribution and wait for CloudFront to be deployed:

CloudFront deployment

Add CNAME Record to DNS

Once your distribution is deployed, create a CNAME record for the subdomain you wish to use along with the distribution URL.

NameValue
Subdomain you wish to use (used in the creation of the distribution).

Note: This will vary based on your DNS provider but will typically be just the subdomain. For example: for cdn.yourdomain.com you would use cdn.
The CDN URL for the created distribution. Example: <prefix>.cloudfront.net
CDN distribution URL

Step 3: Serve SDK

See the following sections to serve the SDK depending on your installation method:

CDN

NPM

Since you have used the NPM module for integrating the SDK directly into your application, there is no configuration required for serving the core SDK.

Additional configuration

Irrespective of your SDK installation method, you will need some additional configuration for loading the device mode destinations and plugins:

Setup for fetching source configuration

When the JavaScript SDK is loaded, it uses the source write key to fetch the required source configuration from RudderStack.

info

The SDK makes a GET request to the https://api.rudderstack.com/sourceConfig URL to fetch the source configuration. It uses the source write key as the authorization header.

For this reason, the distribution settings in this scenario will be slightly different as you need to explicitly allowlist the Authorization header to make sure it is sent along with each request.

Step 1: Configure distribution

The following sections highlight the required distribution settings.

Origin

FieldSetting
Origin domainapi.rudderstack.com
ProtocolHTTPS Only
HTTPS port443
Minimum origin SSL protocolTLSv1.2
Nameapi.rudderstack.com
Enable Origin ShieldNo

Default cache behavior settings

FieldSetting
Compress objects automaticallyYes
Viewer protocol policyRedirect HTTP to HTTPS
Allowed HTTP methodsGET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE
Restrict viewer accessNo

Cache key and origin requests

Select Cache policy and origin request policy (recommended) and configure the following settings:

FieldSetting
Cache policySee Cache policy settings.
Origin request policySee Origin request policy settings.
Response headers policyCORS-With-Preflight
Cache policy settings

Create a cache policy with the following settings:

Custom domains cache policy settings
FieldSetting
Name<CACHE_POLICY_NAME>
Description<CACHE_POLICY_DESCRIPTION>
Minimum TTL1
Maximum TTL86400
Default TTL300
HeadersInclude the following headers
Add headerAuthorization
Origin
Query stringsAll
CookiesNone
Origin request policy settings

Create a new origin request policy with the following settings:

Origin request policy settings
FieldSetting
Namerudderstack-allow-headers
HeadersInclude the following headers
Add header
  • Access-Control-Request-Headers
  • Access-Control-Request-Method
  • Origin
  • Content-Encoding
Query stringsAll
CookiesNone

Additional settings

These are same as the additional distribution settings for serving the JavaScript SDK.

Step 2: Deploy distribution

Click Create distribution and wait for CloudFront to be deployed:

CloudFront deployment

Add CNAME record to DNS

These are same as the settings for serving the JavaScript SDK.

Step 3: Fetch source configuration

To use a custom URL to fetch the source configuration, add it as an option when loading the JavaScript SDK:

rudderanalytics.load(
  <SOURCE_WRITE_KEY>,
  DATA_PLANE_URL,
  {
    configUrl: "https://<YOUR_CUSTOM_DOMAIN>",
  }
)

Setup for sending events

Normally, all tracked events are sent to RudderStack via your data plane URL. To have events routed through your own domain, you need to set up a proxy to that and then use it as the data plane URL while initializing the SDK.

Step 1: Configure distribution

The following sections highlight the required distribution settings.

Origin

FieldSetting
Origin domainDATA_PLANE_URL
ProtocolHTTPS Only
HTTPS port443
Minimum origin SSL protocolTLSv1.2
Name<YOUR_ORIGIN_NAME>
Enable Origin ShieldNo

Default cache behavior settings

FieldSetting
Compress objects automaticallyYes
Viewer protocol policyRedirect HTTP to HTTPS
Allowed HTTP methodsGET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE
Restrict viewer accessNo

Cache key and origin requests

Select Cache policy and origin request policy (recommended) and configure the following settings:

Cache and origin request policy
FieldSetting
Cache policyCachingDisabled
Origin request policySee Origin request policy settings.
Response headers policyCORS-With-Preflight
Origin request policy settings

Create a new origin request policy with the following settings:

Origin request policy settings
FieldSetting
Namerudderstack-allow-headers
HeadersInclude the following headers
Add header
  • Access-Control-Request-Headers
  • Access-Control-Request-Method
  • Origin
  • Content-Encoding
Query stringsAll
CookiesNone

Additional settings

These are same as the additional distribution settings for serving the JavaScript SDK.

Step 2: Deploy distribution

Click Create distribution and wait for CloudFront to be deployed:

CloudFront deployment

Add CNAME record to DNS

These are same as the settings for serving the JavaScript SDK.

Step 3: Send events

Once the setup and DNS propagation is completed, you can use the newly created URL as the data plane URL when initializing the SDK:

Before:

rudderanalytics.load( 
  WRITE_KEY ,
  DATA_PLANE_URL
)

After:

rudderanalytics.load(
  WRITE_KEY,
  "https://<YOUR_CUSTOM_DOMAIN>"
)
info
Make sure that the events are routed through your own domain and not the rudderstack.com domain in the network tab of your browser console. See JavaScript SDK FAQ for more information.

Use custom SSL certificates

info
To use your own domain, you can request or import an SSL certificate with your CDN provider. Note that this is an optional setting.

To use the AWS Certificate Manager with CloudFront, choose the relevant ACM/IAM certificate in the Custom SSL certificate field:

Custom SSL certificate
info
You can choose your subdomain or use a wildcard domain *.yourdomain.com to set up multiple subdomains.

The AWS Certificate Manager will guide you through the verification by email or DNS TXT records. You will be able to choose your own domain for SSL certificates once verified.

FAQ

Can I overcome ad blockers by serving the JavaScript SDK on my domain?

Many popular ad blockers block specific SDK-related downloads and API calls based on the domain name and URL. You can serve the SDK on your CDN to circumvent this issue.

I am using GCP External HTTP(S) Load Balancer to set up my custom domain. Why are any requests from xyz.mydomain.com to cdn.rudderlabs.com resulting in a 403?

If you’re setting up a custom domain using the GCP External HTTPS Load Balancer, make sure you add a custom request header in your backend service config:

Header nameValue
Hostcdn.rudderlabs.com


Questions? Contact us by email or on Slack