> For the complete documentation index, see [llms.txt](https://rudderlabs.gitbook.io/rudderlabs-1/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://rudderlabs.gitbook.io/rudderlabs-1/docs/user-guides/how-to-guides/custom-domains.md).

# How to Use Custom Domains

Use your own domain to serve the RudderStack Javascript SDK and send events to your own domain.

This guide contains the steps to use your own domain to route the events or proxy the [RudderStack JavaScript SDK](https://www.rudderstack.com/docs/stream-sources/rudderstack-sdk-integration-guides/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 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:

| Endpoint             | Description                                                      |
| -------------------- | ---------------------------------------------------------------- |
| `cdn.rudderlabs.com` | Loads the JavaScript SDK.                                        |
| `api.rudderlabs.com` | Fetches the source configuration based on your source write key. |
| `<DATA_PLANE_URL>`   | Required for sending the events to RudderStack.                  |

To use your own domain for these endpoints, you will need to route the traffic through your CDN.

You will incur CDN charges for this traffic if you choose to use your own domain.

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 for serving the SDK

To serve the JavaScript SDK, start by creating a new distribution. The following sections highlight the required distribution settings.

### Origin

![Custom domains distribution settings](https://876606571-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-Lq5Ea6fHVg3dSxMCgyQ%2Fuploads%2Fgit-blob-418e9f152f6fd4fd7d1de0c28adde885198472c8%2Fcustom-domains-1.png?alt=media)

| Field                       | Setting              |
| --------------------------- | -------------------- |
| Origin domain               | `cdn.rudderlabs.com` |
| Protocol                    | HTTPS Only           |
| HTTPS port                  | 443                  |
| Minimum origin SSL protocol | TLSv1                |
| Name                        | `cdn.rudderlabs.com` |
| Enable Origin Shield        | No                   |

### Default cache behavior settings

![Custom domains distribution settings](https://876606571-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-Lq5Ea6fHVg3dSxMCgyQ%2Fuploads%2Fgit-blob-c3378d49cc78461b35e9c21d6c300586e0c39d42%2Fcustom-domains-2.png?alt=media)

| 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

| Field                             | Setting                                |
| --------------------------------- | -------------------------------------- |
| Cache and origin request settings | Cache policy and origin request policy |
| Cache policy                      | CachingOptimized                       |

Click on **Create policy** and refer to the settings in the [Create policy](#create-cache-policy) section below.

### Additional distribution settings

![Custom domains distribution settings](https://876606571-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-Lq5Ea6fHVg3dSxMCgyQ%2Fuploads%2Fgit-blob-117e9e9cb79a2897f77c5718d67529280c298128%2Fcustom-domains-3.png?alt=media)

| Field                        | Setting                                                                                                                                           |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| Price class                  | Use all edge locations(best performance)                                                                                                          |
| Alternate domain name(CNAME) | `<subdomain.yourdomain.com>`                                                                                                                      |
| SSL Certificate              | Add your custom SSL Certificate. Refer to the [Using custom SSL certificates](#using-custom-ssl-certificates) section below for more information. |
| Supported HTTP versions      | HTTP/2                                                                                                                                            |
| Standard logging             | Off                                                                                                                                               |
| IPv6                         | On                                                                                                                                                |

Finally, click on **Create distribution** and wait for CloudFront to be deployed, as shown:

![CloudFront deployment](https://876606571-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-Lq5Ea6fHVg3dSxMCgyQ%2Fuploads%2Fgit-blob-af6934761ac2ffb3756c8919389229ab0a883cdd%2Fcustom-domains-5.png?alt=media)

## Create cache policy settings

![Custom domains create policy settings](https://876606571-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-Lq5Ea6fHVg3dSxMCgyQ%2Fuploads%2Fgit-blob-3ffcbbea92ad3178dd4b0e415556029c433856b4%2Fcustom-domains-4.png?alt=media)

| Field       | Setting                       |
| ----------- | ----------------------------- |
| Name        | \<YOUR\_CACHE\_POLICY\_NAME>  |
| Description | \<CACHE\_POLICY\_DESCRIPTION> |

### TTL settings

| Field        | Setting  |
| ------------ | -------- |
| Minimum TTL  | 1        |
| Maxmimum TTL | 31536000 |
| Default TTL  | 86400    |

### Cache key settings

| Field         | Setting                                        |
| ------------- | ---------------------------------------------- |
| Headers       | Include the following headers                  |
| Add header    | Select `Authorization` from the dropdown list. |
| Query strings | None                                           |
| Cookies       | None                                           |

## Adding CNAME Record to DNS

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

| Name                                                                                                                                                                                                                 | Value                                                                                   |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| Subdomain you wish to use (used in the creation of the distribution). 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 created. Example: `d3jlkfchu4u.cloudfront.net` |

![CDN distribution URL](https://876606571-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-Lq5Ea6fHVg3dSxMCgyQ%2Fuploads%2Fgit-blob-07e037e512f4a3a32b2ec8739f338e695fd73e6c%2Fcustom-domains-6.png?alt=media)

## Serving the SDK

Once the setup and DNS propagation is completed, you will be able to change the SDK URL, as shown:

Before:

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

After:

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

If you are using an older version of the JavaScript SDK (v1), refer to the [Version Migration Guide](https://www.rudderstack.com/docs/stream-sources/rudderstack-sdk-integration-guides/rudderstack-javascript-sdk/version-migration-guide/) to migrate to v1.1.

## Setup for sending events

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

### Required settings

The settings for sending the events will be the same as the settings for serving the JavaScript SDK, except for the following:

| Field                           | Setting                      |
| ------------------------------- | ---------------------------- |
| Origin Domain Name              | `<DATA_PLANE_URL>`           |
| Alternate Domain Names (CNAMEs) | `<subdomain.yourdomain.com>` |

### Adding CNAME record to DNS

The settings for the CNAME record will be the same as the settings for serving the JavaScript SDK. You will need to use the newly created distribution domain and the subdomain you set for it.

### Sending 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, as shown:

Before:

```javascript
rudderanalytics.load( 
  <WRITE_KEY> ,
  "https://hosted.rudderlabs.com"
)
```

After:

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

You should be able to confirm that the events are routed through your own domain and not the `rudderstack.com` domain in the network tab of your browser console.

Refer to this [JavaScript SDK FAQ](https://www.rudderstack.com/docs/stream-sources/rudderstack-sdk-integration-guides/rudderstack-javascript-sdk/js-sdk-faqs/#how-to-check-if-the-data-is-being-transmitted-to-the-desired-destinations) for more information on verifying the flow of events.

## Setup for fetching source configuration

When the JavaScript SDK is loaded, it uses the source write key to fetch the required configuration from RudderStack. This determines which native SDKs may be needed and which destinations are used.

The call to fetch the source configuration is sent to `api.rudderstack.com` with the source `WRITE_KEY` used as an authorization header. For this reason, this distribution will be slightly different as you will need to explicitly whitelist the Authorization header to make sure it is sent along with each request.

### Required settings

The settings for sending events will be the same as the settings for serving the JavaScript SDK except for the following:

| Field                           | Setting                      |
| ------------------------------- | ---------------------------- |
| Origin Domain Name              | `api.rudderlabs.com`         |
| Alternate Domain Names (CNAMEs) | `<subdomain.yourdomain.com>` |

You will also need to whitelist the **Authorization** header in **Cache key settings** by following the steps below:

1. Under **Headers**, choose **Include the following headers** from the dropdown.
2. In the **Add header** field, select **Authorization** from the list of options.

![Whitelist authorization header](https://876606571-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-Lq5Ea6fHVg3dSxMCgyQ%2Fuploads%2Fgit-blob-6c9d1a2bd98147ac20ec5dd22f215fd68abd8d7d%2Fcustom-domains-7.png?alt=media)

### Adding CNAME record to DNS

The settings for the CNAME record will be the same as the settings for serving the JavaScript SDK. You will need to use the newly created distribution domain and the subdomain you set for it.

### Fetching the source configuration

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

```javascript
rudderanalytics.load(
  <SOURCE_WRITE_KEY>,
  "https://hosted.rudderlabs.com",
  {
    configUrl: "https://subdomain.yourdomain.com",
  }
)
```

## Using custom SSL certificates

To use your own domain, you can request or import a 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, as shown:

![Custom SSL certificate](https://876606571-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-Lq5Ea6fHVg3dSxMCgyQ%2Fuploads%2Fgit-blob-63fab111dfcde7303c390c6b22fb3af685ecb128%2Fcustom-domains-8.png?alt=media)

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.

## Contact us

For queries on any of the sections covered in this guide, you can [contact us](mailto:%20docs@rudderstack.com) or start a conversation in our [Slack](https://rudderstack.com/join-rudderstack-slack-community) community.