Use your own domain to serve the RudderStack JavaScript SDK and send events to your own domain.
9 minute read
This guide contains the steps to use your own domain to route the events or proxy the RudderStack JavaScript SDK via your own CDN.
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.
Endpoint details
The following table lists the three endpoints that you need to proxy via your own CDN to route the events:
Endpoint
Description
cdn.rudderlabs.com
Loads the JavaScript SDK.
api.rudderstack.com
Fetches the source configuration based on your source write key.
DATA_PLANE_URL
Required for sending the events to RudderStack. See Glossary for more information on obtaining your data plane URL.
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:
Click Services and go to Network & Content Delivery > CloudFront.
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.
Make sure to replace <YOUR_DOMAIN_URL> in the above snippets with the appropriate values.
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:
Configure the load API option for plugins as follows if you are not using the @rudderstack/analytics-js/bundled package that bundles all the plugins into the SDK package.
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
Field
Setting
Origin domain
DATA_PLANE_URL
Protocol
HTTPS Only
HTTPS port
443
Minimum origin SSL protocol
TLSv1
Name
<YOUR_ORIGIN_NAME>
Enable Origin Shield
No
Default cache behavior settings
Field
Setting
Compress objects automatically
Yes
Viewer protocol policy
Redirect HTTP to HTTPS
Allowed HTTP methods
GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE
Restrict viewer access
No
Cache key and origin requests
Select Cache policy and origin request policy (recommended) and configure the following settings:
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 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
Field
Setting
Origin domain
api.rudderstack.com
Protocol
HTTPS Only
HTTPS port
443
Minimum origin SSL protocol
TLSv1
Name
<YOUR_ORIGIN_NAME>
Enable Origin Shield
No
Default cache behavior settings
Field
Setting
Compress objects automatically
Yes
Viewer protocol policy
Redirect HTTP to HTTPS
Allowed HTTP methods
GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE
Restrict viewer access
No
Cache key and origin requests
Select Cache policy and origin request policy (recommended) and configure the following settings:
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 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?
Why am I getting the Access Denied error on using a custom domain URL for JavaScript SDK?
If you are using the latest JavaScript SDK, paste the SDK snippet in your website’s <head> section and update the URL from:
varsdkBaseUrl="https://cdn.rudderlabs.com/v3";
to:
varsdkBaseUrl="https://<YOUR_DOMAIN_URL>/v3"
Make sure to replace <YOUR_DOMAIN_URL> in the above snippet with the appropriate values.
See the Additional configuration for the correct format to set the custom domain URL for loading device mode destinations and plugins (applicable only for the latest JavaScript SDK).
Legacy SDK
In case of the legacy JavaScript SDK (v1.1 or below), the Access Denied error is encountered if a custom domain URL accesses the JavaScript SDK’s parent folder, as below:
This site uses cookies to improve your experience while you navigate through the website. Out of
these
cookies, the cookies that are categorized as necessary are stored on your browser as they are as
essential
for the working of basic functionalities of the website. We also use third-party cookies that
help
us
analyze and understand how you use this website. These cookies will be stored in your browser
only
with
your
consent. You also have the option to opt-out of these cookies. But opting out of some of these
cookies
may
have an effect on your browsing experience.
Necessary
Always Enabled
Necessary cookies are absolutely essential for the website to function properly. This
category only includes cookies that ensures basic functionalities and security
features of the website. These cookies do not store any personal information.
This site uses cookies to improve your experience. If you want to
learn more about cookies and why we use them, visit our cookie
policy. We'll assume you're ok with this, but you can opt-out if you wish Cookie Settings.