Tracking domain — Voidhash Docs

By default the web SDK sends its requests to api.voidhash.com. A tracking domain is a subdomain of your own site, such as t.example.com, that Voidhash serves for your project. Pointing the SDK at it has two benefits:

Fewer blocked events. Ad blockers and browser tracking prevention often block requests to well-known analytics hosts. Requests to your own domain are blocked far less often.
Accurate locations. Voidhash records the visitor's own IP address and location, as it does for requests to the default address. A reverse proxy you run yourself only passes them on if it forwards the client's address; otherwise every visitor appears to be where your proxy runs.

Tracking domains are available on Voidhash Cloud.

Before you start

You can add DNS records for the domain, for example example.com.
You have permission to edit the project's settings. Without it, you can see the project's tracking domains but not add, check or remove them.

Add the domain

In Studio, open your project's Settings and find the Tracking domain card. Enter the hostname you want to use, for example t.example.com, and select Add domain.

The hostname must be a subdomain. DNS does not allow the record you need at the root of a domain, so example.com cannot be used, but t.example.com can. Pick a neutral name: blocklists also match names such as analytics or tracking.

Create the DNS record

Studio shows the records for the domain. At your DNS provider, create the CNAME record:

Type	Name	Value
`CNAME`	`t.example.com`	`<target>.track.voidhash.link`

<target> is your project's own, for example k2m4p6q7r2s3t4v5; copy the full value from Studio. Pointing the domain at your project's target is what proves the domain belongs to your project, so a domain pointed at another project's target, or at an old one, is never activated for you.

Some DNS providers flatten CNAME records or hide them behind their own proxy, so Voidhash cannot see the record. Studio then also asks for a TXT record, named _voidhash-verify.t.example.com, with a value unique to your domain. Add it, keep the CNAME, and the domain is verified through the TXT record instead.

Studio may also list TXT records marked optional. They only speed up issuing the certificate; the domain works without them.

Wait for the domain to become active

Voidhash checks the domain automatically, every few minutes in its first hour and less often after that. Select Check now to check right away once your record is in place. The domain moves from Waiting for DNS to Issuing certificate, which usually takes a few minutes, and then to Active.

Point the SDK at the domain

Once the domain is active, set it as the SDK's baseUrl:

import { createVoidhashClient } from "@voidhash/web";

export const voidhash = createVoidhashClient({
  baseUrl: "https://t.example.com",
  publishableKey: "vh_pk_…",
});

All of the SDK's requests, both events and feature flags, now go to your domain.

Check it in the browser

Open your site with the browser's developer tools on the Network tab. Requests to t.example.com/i/v1/… and t.example.com/api/v1/sdk/… should succeed, and no requests should go to api.voidhash.com. New events appear in your project as usual.

Moving an existing site to a tracking domain keeps returning visitors as they are: their anonymous ID, consent choice, session, and queued events are stored per project, not per baseUrl.

Statuses

Status	Meaning	What to do
Waiting for DNS	Voidhash cannot see the `CNAME` record to your project's target yet.	Check the record's name and value at your DNS provider. DNS changes can take a while to spread; select Check now later.
Issuing certificate	The record is in place and a certificate is being made.	Wait a few minutes. The optional `TXT` records can speed this up.
Active	The domain is serving your project.	Keep the `CNAME` record in place.
Failed	Studio shows the reason.	If the record was removed or changed, restore it and select Check now. If the certificate could not be issued, check the record, then remove the domain and add it again.

Active domains are checked daily, and must keep proving they belong to your project:

If the CNAME record is changed to point somewhere else, the domain is turned off: it becomes Failed, Studio says where the record now points, and requests through it stop working. Point the record back and select Check now to turn it on again.
If the CNAME record can no longer be seen, for example because you turned on your DNS provider's proxy, the domain keeps working, and Studio asks for the TXT record and shows the date by which to add it. Without it, the domain is turned off after 7 days.

A domain whose DNS records are not in place within 7 days of adding it is removed; add it again when you are ready.

Several projects can add the same hostname. The one whose DNS proves it, by the CNAME to its own target or its own TXT record, gets it, and keeps it while its DNS still proves it. If the hostname's DNS later proves another project instead, for example when the domain moves from an agency's project to your own, the hostname moves to that project and the previous one is told why. If another project already uses a hostname, Studio says so only once your DNS records prove the hostname is yours.

Security

A tracking domain only accepts the publishable key of the project that added it. A request through it with another project's key is rejected with 401, so pointing a domain at Voidhash does not let anyone send events to another project. Secret keys and personal API keys are rejected on a tracking domain too: they belong on your server, never in a browser; send server-side events to https://api.voidhash.com directly. Only the SDK's endpoints are served on a tracking domain; any other path answers 404.

Adding and removing tracking domains is recorded in the project's audit log.

Limits

A project can have up to 5 tracking domains, for example one per website. Each hostname serves only one project.

Remove a domain

Point the SDK's baseUrl back at its default address, or at another active tracking domain, and deploy that change first. Then remove the domain in Studio. Requests through a removed domain stop working shortly after, and events sent through it are lost. You can delete the CNAME record afterwards.

Self-hosted Voidhash

Self-hosted installs do not offer hosted tracking domains. Your Voidhash API already runs on a domain you control. To serve the SDK from your website's own domain, put a reverse proxy in front of it; see First-party proxy.