# Custom Domain (CNAME)

> Current Froomle documentation · [View canonical page](https://docs.froomle.com/froomle-doc-main/v2/guide/topics/custom-domain-cname.html)

Use this guide when you want Froomle traffic to run on your own subdomain, for example `froomle.yourdomain.com`, instead of the default `europe-west1.froomle.com`.

<a id="_dns_setup"></a>

## DNS Setup

<a id="_step_1_create_a_cname_record"></a>

### Step 1: Create a CNAME record

Choose a subdomain and create a DNS CNAME record:

| Field | Value |
| --- | --- |
| Type | `CNAME` |
| Name | `froomle.yourdomain.com` (example) |
| Target / Destination | `europe-west1.froomle.com` |

> **IMPORTANT:**
> 
> Use a subdomain. Do not use the zone apex (`yourdomain.com`) for this CNAME setup.

<a id="_step_2_add_caa_records"></a>

### Step 2: Add CAA records

To allow automatic SSL certificate issuance and renewal for your custom subdomain, add these CAA records:

```text
0 issue "pki.goog"
0 issue "letsencrypt.org"
```

If your DNS provider requires full record fields, use:

```text
Type: CAA
Name: froomle.yourdomain.com
Flags: 0
Tag: issue
Value: "pki.goog"

Type: CAA
Name: froomle.yourdomain.com
Flags: 0
Tag: issue
Value: "letsencrypt.org"
```

<a id="_notify_froomle"></a>

## Notify Froomle

After DNS records are in place, send your chosen custom subdomain to the Froomle team so we can configure our load balancer to accept traffic for that domain.

Provide:

-   The custom subdomain (for example `froomle.yourdomain.com`)
    
-   The environment(s) where it should be active
    
-   Your intended go-live timing
    

<a id="_update_your_integration"></a>

## Update Your Integration

<a id="_frontend_sdk"></a>

### Frontend SDK

Set the request domain in your integration:

-   SDK package: [@froomle/frontend-sdk on npm](https://www.npmjs.com/package/@froomle/frontend-sdk)
    
-   JS/TS API: `setRequestDomain('froomle.yourdomain.com')`
    
-   Script-tag integration: `data-froomle-request-domain="froomle.yourdomain.com"`
    
-   Integrations using runtime request variables: set `request_domain` to your custom domain
    

Example (module/import):

```ts
import { setRequestDomain } from '@froomle/frontend-sdk'

setRequestDomain('froomle.yourdomain.com')
```

Example (script tag):

```html
<script
  src="https://cdn.jsdelivr.net/npm/@froomle/frontend-sdk@latest/dist/froomle.global.js"
  data-froomle-env="your_env"
  data-froomle-page-visit="home"
  data-froomle-request-domain="froomle.yourdomain.com"
></script>
```

<a id="_direct_api_calls"></a>

### Direct API Calls

If you call APIs directly, use your custom hostname in request URLs.

Example:

```text
https://froomle.yourdomain.com/api/\{environment\}/recommendations/requests
```

<a id="_browser_credentials_and_cookies"></a>

#### Browser Credentials and Cookies

The Froomle frontend SDK omits browser credentials from recommendation requests, including when the API uses a custom domain. Explicit recommendation bearer authentication configured in the SDK remains supported; the SDK only adds that header when a token is configured.

If direct API calls are made from a browser without the SDK, configure those requests to omit credentials/cookies. Because the custom domain is same-site with your own website, browsers may attach your site’s cookies automatically. Froomle APIs do not need these cookies.

Keep the explicit headers required by the API, such as `Authorization` and `Content-Type`.

Example with `fetch`:

```js
fetch(url, {
  method: 'POST',
  credentials: 'omit',
  headers: {
    Authorization: `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(payload),
})
```

If you use another HTTP client, use the equivalent setting, for example `withCredentials: false` for Axios or XMLHttpRequest.

<a id="_verification"></a>

## Verification

Before go-live:

1.  Confirm DNS resolves to `europe-west1.froomle.com`.
    
2.  Confirm HTTPS works on your custom subdomain.
    
3.  Confirm recommendation requests are sent to your custom domain.
    

Related:

-   [Account setup](https://docs.froomle.com/froomle-doc-main/v2/guide/account-setup.html)
    
-   [Authentication flow](https://docs.froomle.com/froomle-doc-main/v2/guide/topics/authentication-flow.html)
    
-   [SDK request domain settings](https://docs.froomle.com/froomle-doc-main/v2/js_lib/jslib.html#ParamReqDom)