> ## Documentation Index
> Fetch the complete documentation index at: https://docs.verisoul.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Hostname

> Serve the Verisoul Web SDK from a custom hostname for first-party delivery

Verisoul strongly recommends serving the Web SDK from a custom hostname that you control, such as `js.example.com` or `v.example.com`.

When the SDK is loaded from the default `js.verisoul.ai` hostname, 4-6% of traffic may be blocked by ad blockers or privacy extensions. A custom hostname delivers the SDK from your own domain and helps preserve signal coverage for production integrations.

## Why use a Custom Hostname?

* **First-party context** - Requests originate from a hostname you own, which helps avoid some ad blockers and privacy extensions.
* **Higher signal coverage** - Loading the SDK from your domain helps prevent the 4-6% traffic loss that can happen when extensions block third-party script hostnames.
* **Simpler CSP rules** - Instead of allowing `*.verisoul.ai`, you can allow a single hostname that you control.
* **Brand consistency** - The SDK URL looks like the rest of your application assets.
* **No backend changes** - Your backend still calls Verisoul APIs directly. Only the browser SDK script URL changes.

## Before you start

You will need:

* Access to your DNS provider.
* A hostname you can delegate to Verisoul, such as `js.example.com` or `v.example.com`.
* Your Verisoul project ID for the environment you are integrating.

Choose a short, ordinary hostname that matches your application domain. Avoid labels that can look suspicious to users or filtering tools, such as `fingerprint`, `telemetry`, or `verisoul`.

## Custom Hostname Setup Guide

Open the Verisoul Dashboard and go to **Settings -> Custom Hostname**.

### 1. Add the hostname

Click **Add Hostname** and enter the hostname you want to use.

For example, if your site is `https://example.com`, common choices are:

* `js.example.com`
* `v.example.com`

The dashboard will create DNS records for the environment you are configuring. In production, the hostname is used directly. In non-production environments, the dashboard may show an environment-specific hostname such as `sandbox.js.example.com`.

<Note>
  In production, Verisoul also prepares the matching sandbox hostname automatically, such as `sandbox.js.example.com`. You only delegate the hostname you entered once.
</Note>

### 2. Add the nameserver records

The dashboard will show nameserver records. Add each NS record at your DNS provider exactly as shown. The record will follow the following format:

```text theme={null}
Type:   NS
Name:   js
Value:  ns-cloud-a1.googledomains.com
```

You will see four nameserver values. Add all four.

You do not need to add any `_acme-challenge` records. Verisoul manages certificate verification records, A records, and environment-specific hostnames inside the delegated DNS zone.

### 3. Verify and activate

DNS changes can take a few minutes to propagate. Once the records are in place, click **Verify DNS & Activate** in the dashboard.

Verisoul will:

1. Verify that the NS records are visible publicly.
2. Issue the HTTPS certificate.
3. Verify that the hostname routes to Verisoul.
4. Mark the hostname as active.

### 4. Update your integration

Once the hostname is active, update your script tag to load the SDK from your custom hostname:

```html theme={null}
<script
  async
  src="https://js.example.com/bundle.js"
  verisoul-project-id="{project_id}">
</script>
```

Replace `js.example.com` with your custom hostname and `{project_id}` with your Verisoul project ID.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Verification is not ready">
    DNS may still be propagating. Confirm that all four NS records were added at the exact hostname shown in the dashboard, then click **Verify DNS & Activate** again.
  </Accordion>

  <Accordion title="Routing is not ready">
    Confirm that the NS records were added at the hostname shown in the dashboard. Add all four nameserver values.
  </Accordion>

  <Accordion title="DNS only works from some networks">
    Recursive DNS resolvers can update at different times. It is normal for one network to see the new route before another network. Use multiple resolvers, such as `1.1.1.1` and `8.8.8.8`, to check propagation.
  </Accordion>

  <Accordion title="An old CNAME still exists">
    If there is an old CNAME at the same hostname, it can shadow the NS records. Remove the old CNAME when you are ready to use the NS-delegated custom hostname.
  </Accordion>

  <Accordion title="The certificate is ready, but the browser cannot load the SDK">
    Check whether the hostname resolves publicly and loads over HTTPS:

    ```bash theme={null}
    dig js.example.com A @1.1.1.1
    curl -I https://js.example.com/bundle.js
    ```

    If DNS resolves but the request still fails, contact Verisoul support with the hostname and the DNS records shown in the dashboard.
  </Accordion>
</AccordionGroup>