# Custom Domains

Custom domains route the Freshpaint Web SDK and all tracking endpoints through a subdomain you own. Browsers treat requests to your domain as first-party traffic, which ad blockers and privacy tools are far less likely to block. The result is more accurate data collection and a cleaner network footprint for your site.

This page helps you:

* Understand why custom domains improve data accuracy
* Know what to prepare before setup begins
* Follow along during the setup process with your Freshpaint team
* Update your Freshpaint snippet once setup is complete

###  1. Why Custom Domains Matter

#### 1.1 Ad Blocker Resilience

Ad blockers maintain lists of known third-party tracking domains. When Freshpaint loads from its default domains, some browsers block those requests entirely — meaning you lose visibility into that user's behavior. A custom domain routes all Freshpaint traffic through a hostname you own, so browsers treat it as first-party and ad blockers typically allow it through.

{% hint style="info" %}

####  Related: For background on how ad blockers affect analytics, see [How do I circumvent ad blockers?](/reference/faqs/how-do-i-circumvent-ad-blockers.md)

{% endhint %}

#### 1.2 Brand Consistency

Network requests from your site point to your own hostname rather than a third-party domain. This provides a cleaner experience if your users or engineering team inspect network traffic.

#### 1.3 Single Hostname

Custom domains consolidate all Freshpaint services — the SDK, tracking API, event definitions, and impression beacon — behind one hostname. No need to manage multiple endpoints.

### 2. Prerequisites

Before reaching out to Freshpaint, confirm the following:

* A domain you control — You need DNS access to the domain where you want to create a subdomain (for example, if your site is `yoursite.com`, you might use `data.yoursite.com`).
* Someone who can add DNS records — You will need to add two CNAME records during setup. Confirm you can make DNS changes or coordinate with your IT team ahead of time.
* A subdomain name that avoids blocked keywords — See guidance below.

{% hint style="warning" %}
Choose your subdomain carefully. Ad blockers scan hostnames for common tracking-related words. Avoid `track`, `tracking`, `analytics`, `pixel`, `beacon`, `collect`, and `telemetry`. Choose something neutral like `data.yoursite.com`, `edge.yoursite.com`, or `cdn.yoursite.com`.<br>
{% endhint %}

### 3. Setup Process

Custom domain setup is handled by the Freshpaint team — there is no self-serve configuration. Your customer success team or support will walk you through each step. Here is what to expect.

#### 3.1 Request Setup

Contact your Freshpaint CSE or email <support@freshpaint.io> with:

* Your account information
* The custom subdomain you want to use (for example, `data.yoursite.com`)

#### 3.2 Freshpaint Provisions Your Infrastructure

The Freshpaint team creates the infrastructure to serve all Freshpaint services through your domain. This step is handled entirely on our side.

#### 3.3 Configure DNS Records

Freshpaint provides you with two DNS records to add in your DNS provider. The Freshpaint team will walk you through this step and verify the records are configured correctly.

1. Certificate validation record — proves domain ownership so a TLS certificate can be issued for your subdomain. Certificate validation typically takes a few minutes but can take up to a few hours.
2. Domain routing record — points your subdomain to the Freshpaint infrastructure. This is added after the certificate is issued.

#### 3.4 Freshpaint Verifies and Activates

Once both DNS records are in place, the Freshpaint team verifies that your custom domain is resolving correctly and all Freshpaint endpoints are reachable. Freshpaint confirms your domain is active and ready to use.

#### 3.5 Update Your Freshpaint Snippet

Update the Freshpaint snippet on your site to include the `custom_domain` parameter. You can find your updated snippet in the Freshpaint dashboard under your environment's setup instructions after setup is complete. The Freshpaint team will flag when this is ready for you!

{% hint style="success" %}
No data loss during migration. Events continue flowing through Freshpaint's default endpoints until the updated snippet is deployed. Once live, traffic seamlessly shifts to your custom domain.
{% endhint %}

### 4. Content Security Policy (CSP)

If your site uses a Content Security Policy header, you must add your new subdomain to the `connect-src` and `script-src` directives. Otherwise, browsers will block requests to your custom domain even though DNS and infrastructure are working correctly. Coordinate with your engineering team if you are unsure whether your site uses CSP.

### 5. Migrating from Legacy Ad Block Bypass

If you are already using the Ad Block Bypass feature described in [How do I circumvent ad blockers?](vscode-file://vscode-app/Applications/Cursor.app/Contents/Resources/app/out/vs/code/electron-sandbox/workbench/link), custom domains are the recommended upgrade. Custom domains consolidate all Freshpaint services behind a single hostname you own, replacing the previous multi-endpoint approach.

To migrate, contact your CSE or <support@freshpaint.io>. The Freshpaint team handles the transition — you only need to update your snippet once the new domain is ready.

### Best Practices & Reminders

* Pick a neutral subdomain name Avoid terms that ad blockers target — `track`, `analytics`, `pixel`, `beacon`, `collect`, or `telemetry`. A generic name like `data`, `edge`, or `cdn` works well.
* Update the snippet promptly after setup&#x20;
  * Your custom domain is only effective once the updated snippet with the `custom_domain` parameter is deployed. Until then, requests continue through default Freshpaint domains.
* Coordinate with your IT and engineering teams early DNS changes and snippet updates may involve different teams. Loop everyone in at the start so the process goes smoothly.
* Keep your DNS records in place Removing the CNAME records for your custom domain or the certificate validation will break the integration. Treat these DNS records as permanent.
* Check your Content Security Policy If your site enforces CSP headers, the new subdomain must be allowed in `connect-src` and `script-src`.

### What's Next?

* Request setup — Email <support@freshpaint.io> or contact your CSE with your account name, preferred subdomain, and DNS access confirmation.
* Verify data flow — Once the snippet is live, check your Freshpaint dashboard to confirm events are arriving through your custom domain.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://documentation.freshpaint.io/readme/custom-domains.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.