Domain filtering
What is domain filtering?
domains is a top-level configuration option that acts as an allowlist of hosts where the SDK is permitted to run. When the current page doesn’t match any entry, the SDK does not initialize — no analytics, tags, push, hx, or session replay. The auto-conf fetch itself still runs.
Typical use case: your tag is public in page markup, and you want to prevent it from being reused on domains you don’t control (scrapers, mirror sites, white-label misuse).
{
"domains": ["domain.com", "*.domain.com"]
}
Presence is the enable
If
domains is absent, not an array, or an empty array [], the filter is off and the SDK boots everywhere. A non-empty array turns the allowlist on.Pattern reference
Each entry in the array is matched independently — one match in the list is enough.
| Pattern | Compared against | Matches | Does not match |
|---|---|---|---|
domain.com | hostname | domain.com exactly, case-insensitive | sub.domain.com, not-domain.com, domain.com.evil.com, domainXcom |
*.domain.com | hostname | any depth under it: sub.domain.com, a.b.domain.com | apex domain.com, not-domain.com, domain.com.evil.com |
localhost:8080 | host (with port) | localhost:8080 | localhost:80 |
https://domain.com | origin | that exact origin | http://domain.com, https://sub.domain.com |
^sub\.domain\.com$ or /^sub\.domain\.com$/ | hostname, as regex | whatever the regex says; only the i flag is allowed | — |
^.*\.domain\.com$ | hostname, as regex | any subdomain | apex |
Matching rules
- A string is treated as a regex only when wrapped in
/…/or starting with^/ ending with$. A baredomain.comis never compiled as a regex — the dot is literal. - One match in the list is enough. Bad entries are skipped and never abort boot.
- Invalid regex, patterns over 256 characters, and empty/whitespace strings are skipped (fail closed for that entry).
*anywhere except the leading*.is rejected:*domain.comand*.*.domain.commatch nothing.domainsabsent, not an array, or[]— filter off, SDK boots everywhere.- A miss on every entry — the SDK does not initialize: no analytics, tags, push, hx, or session replay. The auto-conf fetch itself still runs.
Set only via auto-conf or init
domains can only be set through auto-conf or Hood('init', tag, config). data-* markup cannot set it, and auto-conf overwrites a page-set value even under no-override — otherwise a pre-init Hood('config', 'domains', []) could punch through the allowlist.Common recipes
| Goal | List |
|---|---|
| Apex only | ["domain.com"] |
| Subdomains only | ["*.domain.com"] |
| Apex + all subdomains | ["domain.com", "*.domain.com"] |
| One specific subdomain | ["sub.domain.com"] |
Example
Hood('init', 'TAG_ID', {
analytics: true,
domains: ['domain.com', '*.domain.com', 'localhost:8080'],
});
With this configuration the SDK runs on the apex, any subdomain at any depth, and your local development server — and nowhere else.
Related
- Manual initialization — all
Hood('init')configuration options - Configuration overview — precedence and protected keys