How to use custom domains

This guide contains the steps to use your own domain to route the events or proxy the RudderStack JavaScript SDK via your own CDN.

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.

Endpoint details

The following table lists the three endpoints to be proxied via your own CDN to route the events:

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

To serve the JavaScript SDK, 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 use case/scenario.

Setup for serving SDK

The following sections highlight the required distribution settings for serving the SDK via RudderStack CDN (cdn.rudderlabs.com).

Origin

The following table summarizes the settings:

Default cache behavior settings

The following table summarizes the settings:

Cache key and origin requests

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

The following table summarizes the settings:

Origin request policy settings

Create a new origin request policy with the following settings:

Additional distribution settings

The following table summarizes the settings:

Create and deploy distribution

Click Create distribution and wait for CloudFront to be deployed:

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.

Serve the SDK

Once the setup and DNS propagation is completed, change the SDK URL from:

 <script src="https://cdn.rudderlabs.com/v1.1/rudder-analytics.min.js"></script>

To:

<script src="https://subdomain.yourdomain.com/v1.1/rudder-analytics.min.js"></script>

To load a device mode SDK, use the following URL:

<script>
rudderanalytics.load(WRITE_KEY, DATA_PLANE_URL, {
    destSDKBaseURL: "https://subdomain.yourdomain.com/v1.1/js-integrations"
});
</script>

If you are using an older version of the JavaScript SDK (v1), see Version Migration Guide to migrate to v1.1.

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.

Origin

Default cache behavior settings

Cache key and origin requests

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

Origin request policy settings

Create a new origin request policy with the following settings:

Additional settings

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

Add CNAME record to DNS

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

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> ,
  "https://hosted.rudderlabs.com"
)

After:

rudderanalytics.load(
  <WRITE_KEY>,
  "https://subdomain.yourdomain.com"
)

Note that:

• 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.
• Load the SDK via your subdomain after making the cookies first-party to avoid adblocking or third-party issues and correctly send or use anonymousId.

Setup for fetching source configuration

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

The SDK sends a call to fetch the source configuration api.rudderstack.com, with the source write key as an authorization header. For this reason, the distribution settings for 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.

Origin

Default cache behavior settings

Cache key and origin requests

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

Cache policy settings

To fetch source config via api.rudderstack.com, create a cache policy with the following settings:

Origin request policy settings

Create a new origin request policy with the following settings:

Additional settings

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

Add CNAME record to DNS

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

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>,
  "https://hosted.rudderlabs.com",
  {
    configUrl: "https://subdomain.yourdomain.com",
  }
)

Use custom SSL certificates

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:

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 adblockers by serving the JavaScript SDK on my domain?

Many popular adblockers 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. However any requests from xyz.mydomain.com to cdn.rudderlabs.com result in a 403. What should I do?

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:

I am getting the Access Denied error on using a custom domain URL for JavaScript SDK. What might be the reason?

The Access Denied error is encountered if a custom domain URL accesses the JavaScript SDK’s parent folder, as below:

<script src="https://subdomain.yourdomain.com/v1.1/js-integrations"></script>

The correct custom domain URL to access the JavaScript SDK should be in the following format:

<script src="https://subdomain.yourdomain.com/v1.1/rudder-analytics.min.js"></script>

The correct custom domain URL to load a device-mode SDK should be in the following format:

<script>
rudderanalytics.load(WRITE_KEY, DATA_PLANE_URL, {
    destSDKBaseURL: "https://subdomain.yourdomain.com/v1.1/js-integrations"
});
</script>

Questions? Contact us by email or on Slack