Send Events via Custom Domains

This guide covers the steps to use your own domain instead of the RudderStack domains for sending events to the RudderStack backend (data plane).

Setup overview

Usually, 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 and then use it as the data plane URL while initializing the SDK.

Create a new distribution by following 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 routing the events through your own domain:

Step 1: Configure distribution

The following sections highlight the required distribution settings:

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 distribution settings

The following table summarizes the settings:

Step 2: 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.

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>"
)

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.

Proxy Beacon batches through a custom path

The EasyPrivacy list, which uBlock Origin and Brave use by default, blocks requests to /beacon/v1/batch on any host, including your custom domain. To send Beacon batches through a neutral path on your custom domain, use beaconQueueOptions.deliveryPath (JavaScript SDK v3.36.1 and later) and rewrite the path in CloudFront:

1. Create a CloudFront Function with the cloudfront-js-2.0 runtime and the following code:

   javascript Copy

   function handler(event) {
     var req = event.request;
     if (req.uri === '/batch') {
       req.uri = '/beacon/v1/batch';
     }
     return req;
   }

2. Publish the function. Create a cache behavior with path pattern /batch pointing to the same data plane origin. Use the Default cache behavior settings, the CachingDisabled cache policy, the Origin request policy settings, and the CORS-With-Preflight response headers policy prescribed for event requests. Keep Query strings set to All: Beacon sends writeKey in the query string.

3. Associate the function with this behavior’s Viewer request event. Rewriting the URI doesn’t change the selected cache behavior or origin, so the /batch behavior must point to your data plane.

4. Set the SDK options:

   javascript Copy

   rudderanalytics.load(WRITE_KEY, "https://<YOUR_CUSTOM_DOMAIN>", {
     useBeacon: true,
     beaconQueueOptions: {
       deliveryPath: "/batch"
     }
   });

The SDK sends batches to https://<YOUR_CUSTOM_DOMAIN>/batch?writeKey=<writeKey>. The function rewrites the path to /beacon/v1/batch and leaves the query string unchanged. If your data plane URL includes a path prefix, match the full incoming path in both the cache behavior and the function. See Send events using Beacon for path validation and defaults.

Only set deliveryPath when your proxy rewrites the custom path to /beacon/v1/batch. The RudderStack data plane only accepts /beacon/v1/batch for Beacon batches and rejects requests without this rewrite. Beacon is fire-and-forget, so the SDK cannot retry these requests and the events are lost.

Use custom SSL certificates

To use a custom domain for your use case, 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.

Custom request header for GCP external load balancer

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