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.

Legacy custom hostnames used a traffic CNAME that pointed to Verisoul’s older custom hostname infrastructure. New custom hostnames use a certificate verification CNAME and nameserver delegation to route SDK traffic through Verisoul. Use this guide if you already have a custom hostname and need to migrate it to the new flow.
If you are setting up a new hostname instead, follow the Custom Hostname Setup Guide.

​
How to know if you need to migrate

In the Verisoul Dashboard, go to Settings → Custom Hostname. If your existing hostname has a Migrate button next to it, it is using the legacy custom hostname flow.

​
What changes during migration

Before migration, your DNS provider usually has a CNAME similar to: 
Type:   CNAME
Name:   js
Value:  js-cname.verisoul.ai
After migration, Verisoul uses:
  • A CNAME for _acme-challenge.<hostname> to verify certificate ownership.
  • NS records for the custom hostname so Verisoul can route SDK traffic.
Your final SDK URL remains the same hostname, but the underlying DNS routing changes. You do not need to change your integration code; your existing script tag will continue to work after the DNS cutover.

​
Migration steps

​
1. Start the migration

In Settings → Custom Hostname, click Migrate next to the legacy hostname. The dashboard will open a migration flow for that hostname.

​
2. Verify certificate ownership

Add the _acme-challenge CNAME shown in the dashboard. If your DNS provider already has an _acme-challenge CNAME for this hostname, replace it with the value shown in the dashboard. This only affects certificate verification and does not route live traffic. Click Verify Certificate and wait for the dashboard to show that the certificate is ready.

​
3. Replace the legacy traffic CNAME with NS records

After the certificate is ready, the dashboard will show the nameserver records to add. At your DNS provider:
  1. Delete the legacy traffic CNAME for the custom hostname.
  2. Add all four NS records shown in the dashboard.
  3. Keep the _acme-challenge CNAME from the certificate step.
Brief downtime is possible during this DNS cutover. Most migrations should settle in a few seconds, but plan for 2-3 minutes of disruption while recursive DNS resolvers switch from the old CNAME path to the new NS records.Longer downtime is atypical but possible if a device, browser, local network, or ISP resolver holds stale DNS or NXDOMAIN cache longer than expected. This is a DNS propagation issue, not an indication that the Verisoul certificate or SDK endpoint is unavailable.

​
4. Verify and activate

Return to the dashboard and click Verify & Activate. Verisoul will verify that DNS routes to Verisoul and then mark the hostname active. After activation, the SDK should continue loading from the same URL: 
<script
  src="https://js.example.com/bundle.js"
  verisoul-project-id="{project_id}">
</script>

​
Zero-downtime alternative

If your integration is latency-sensitive or cannot tolerate any potential DNS cutover window, use a new hostname instead of migrating the existing one. For example:
  1. Keep the legacy hostname live, such as js.example.com.
  2. Set up a new hostname, such as js2.example.com, using the Custom Hostname Setup Guide.
  3. Deploy an application change that updates the SDK script URL from js.example.com to js2.example.com.
This approach avoids the DNS record-type switch at the existing hostname. It also lets you test the new hostname end-to-end before sending production traffic to it.

​
Troubleshooting

If the legacy CNAME remains at the same DNS name, some resolvers may continue to route traffic through the old path. Delete the old traffic CNAME when you are ready to cut over.
Add the NS records at the DNS name shown in the dashboard. In non-production environments, the routed hostname may include an environment prefix, such as dev.js.example.com or sandbox.js.example.com.
Different recursive resolvers can observe DNS changes at different times. This is expected during a DNS cutover. Check propagation from multiple resolvers:
dig js.example.com A @1.1.1.1
dig js.example.com A @8.8.8.8
The browser, device, local router, or ISP resolver may have stale DNS cache. Try a different network, flush local DNS cache, or wait for the stale cache to expire.