A custom subdomain allows you to host the Verisoul Web SDK under a URL that matches your domain (e.g., js.mywebsite.com).

​
Why Use a Custom Subdomain?

  • First-party context – Requests originate from a subdomain you own which prevents some ad-blockers / privacy extensions from blocking the SDK.
  • Simpler CSP rules – Instead of allowing *.verisoul.ai, you can allow a single sub-domain you control.
  • Brand consistency – The SDK URL looks like the rest of your assets.
  • No impact on server-side APIs – Your backend still calls api.{env}.verisoul.ai; only the <script> tag changes.

​
Setup Guide

Follow the steps below in the Verisoul Dashboard → Developer → Custom Subdomain section.

​
1. Register the subdomain

  1. Click Add Subdomain and enter the hostname you would like to use.

  2. The hostname must exactly match your website’s origin. For example:

    • Site at https://mywebsite.com can use:

      • js.mywebsite.com
      • v.mywebsite.com

    • Avoid keywords that could look suspicious:

      • verisoul.mywebsite.com
      • telemetry.mywebsite.com
      • fingerprint.mywebsite.com

  3. The subdomain should be only one level below your apex domain (e.g., js.mywebsite.com). Wild-card and multi-level names are not supported.

​
2. Add the SDK CNAME record

Create a CNAME record in your DNS provider pointing your subdomain to js-cname.verisoul.ai.

Type:   CNAME
Name:   js 
Value:  js-cname.verisoul.ai
TTL:    60

If you manage DNS with Cloudflare set the record to DNS-only (grey cloud). The SDK is already cached on Verisoul’s edge, so additional Cloudflare proxying is not required.

​
3. Verify ownership (TLS CNAME)

Immediately after registration the dashboard will show a second CNAME that Verisoul uses to issue an HTTPS certificate. Add this record exactly as provided.

You will see one of three statuses:

StatusMeaning
processingVerisoul is provisioning the TLS certificate.
pending_validationWe have not detected the CNAME yet – check that the record is present and has propagated.
activeThe certificate is issued and your subdomain is ready to use.

​
4. Update your integration

Once the status turns active, replace the default script tag with your new subdomain:

<script
  src="https://js.company.com/{env}/bundle.js"
  verisoul-project-id="{project_id}">
</script>

No other code changes are necessary.

​
Deleting or Refreshing Validation

  • Delete – You can remove a subdomain at any time in the dashboard. This immediately stops the SDK from loading at that URL, so be sure to update your site before deleting.
  • Refresh – If validation is stuck in pending_validation click Refresh. Verisoul will re-check DNS and usually updates within a minute once the CNAME has propagated.

After deleting a subdomain it may take several minutes for caches to expire. Users who still reference the old URL will receive 404 responses until the new script tag is shipped.

​
Troubleshooting

  1. Use dig or an online DNS checker to confirm that both CNAME records are visible publicly.
  2. Ensure any CDN or DNS proxy (e.g., Cloudflare orange cloud) is disabled.
  3. Wait for DNS TTL — most issues resolve once the record propagates globally.