Skip to main content

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.

A custom hostname lets you serve the Verisoul Web SDK from a domain you control, such as js.example.com or v.example.com.

​
Why use a Custom Hostname?

  • First-party context - Requests originate from a hostname you own, which helps avoid some ad blockers and privacy extensions.
  • 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.
Migrating an existing legacy custom hostname? Follow Legacy Hostname Migration instead.

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

​
2. Verify certificate ownership

The dashboard will show a DNS record for certificate verification. Add the record exactly as shown. The record will follow the following format: 
Type:   CNAME
Name:   _acme-challenge.js.example.com
Value:  _acme-challenge.js.example.com.acme.verisoul.ai
This record is used only to verify that you control the hostname and to issue the HTTPS certificate. After you add the record, return to the dashboard and click Verify Certificate. The dashboard will check DNS automatically until the certificate is ready.

​
3. Route traffic to Verisoul

After the certificate is ready, the dashboard will show nameserver records. Add each NS record at your DNS provider exactly as shown. The record will follow the following format: 
Type:   NS
Name:   js
Value:  ns-cloud-a1.googledomains.com
You will see four nameserver values. Add all four. DNS changes can take a few minutes to propagate. Once the records are in place, click Verify & Activate in the dashboard. Verisoul will verify that the hostname routes to Verisoul and then mark it as active.

​
4. Update your integration

Once the hostname is active, update your script tag to load the SDK from your custom hostname: 
<script
  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

Confirm that the _acme-challenge CNAME exists publicly and points to the exact value shown in the dashboard. If the record points to an old value, replace it with the current dashboard value.
DNS providers sometimes append your domain automatically. Make sure the final record value matches the dashboard value exactly. If your provider requires a trailing dot, use the trailing-dot version of the same hostname.
Confirm that the NS records were added at the hostname shown in the dashboard. Add all four nameserver values.
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.
If there is an old CNAME at the same DNS name, it can shadow the NS records. Delete or replace the old CNAME when you are ready to route traffic to Verisoul.
Check whether the hostname resolves publicly and loads over HTTPS:
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.