Custom Domain (CNAME)

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.

DNS Setup

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

Use a subdomain. Do not use the zone apex (yourdomain.com) for this CNAME setup.

Step 2: Add CAA records

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

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

If your DNS provider requires full record fields, use:

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"

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

Update Your Integration

Frontend SDK

Set the request domain in your integration:

  • SDK package: @froomle/frontend-sdk on npm

  • 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):

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

setRequestDomain('froomle.yourdomain.com')

Example (script tag):

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

Direct API Calls

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

Example:

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

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:

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.

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: