Your extension groups shop.example.co.uk under co.uk, then applies one rule to unrelated sites. The parser split on dots and kept the last two labels. That shortcut cannot describe the Public Suffix List.
A hostname with three labels can represent one site, several tenants, or a public suffix boundary. The Chrome publicSuffix API moves that decision into the browser.
Myth and reality
Myth: the registrable domain is always the final two labels.
Reality: the boundary depends on the browser’s current Public Suffix List and on how your product treats private or unknown names.
Use the Chrome publicSuffix API for one explicit job
Chrome’s API reference makes the surface available in Chrome 153 and later with the publicSuffix permission. getDomain() returns the registrable domain, getKnownSuffix() returns the known suffix, and isKnownSuffix() checks whether a hostname is itself a public suffix.
Choose the method from the product decision. Grouping tabs or settings by site usually needs the registrable domain. Warning that a requested cookie or rule targets a suffix needs the suffix check. Do not call all three and invent precedence afterward.
Migration sequence
- Inventory every custom parser and bundled suffix dataset.
- Add the permission and a capability check.
- Replace one decision point with the browser result.
- Run the edge-case corpus in Chrome 153 and fallback browsers.
- Remove the dataset only after telemetry shows equivalent intent.
Define options instead of accepting defaults by accident
getDomain() can allow IP addresses, plain suffixes, and unknown suffixes through explicit options. The defaults reject those cases. That conservative behavior is useful for internet-site grouping, but an enterprise extension may also see printers, development hosts, or split-horizon names.
Write a product rule for each case. An IP address can stay an address rather than a site. An unknown suffix can remain ungrouped or enter a separately labeled internal-host path. A known public suffix should never become the account or tenant identity by itself.
The API also supports punycode and display encodings. Ask for display encoding only when a person will see the value, and keep the canonical network form for comparisons and storage.
Unicode display can be safer than a raw decoded string because the browser may preserve punycode when characters are confusable. Keep that safety decision in the platform layer rather than writing a second decoder.
Keep a cross-browser fallback without keeping two truths
Chrome’s extension changelog marks the API as a Chrome 153 addition. Other browsers or older enterprise channels may expose a related WebExtensions API, expose a different namespace, or expose nothing.
Detect the method at runtime. When it exists, use the browser answer. When it does not, call one isolated fallback implementation with a versioned dataset and the same output contract. Do not let feature code decide which parser to trust.
Fallback policy
Browser API available: browser result is authoritative for that profile.
API unavailable: versioned fallback handles supported cases and returns unknown outside them.
Results differ in tests: log the case, preserve behavior, and investigate before rollout.
The WebExtensions proposal identifies dataset and interpretation drift as a reason for the API. Bundling a list for the fallback remains an operational burden, so expose its age and update path.
Test decisions, not a list of favorite domains
Create a corpus with multi-label suffixes, private suffixes relevant to your users, ordinary domains, single-label hosts, unknown internal suffixes, IPv4, IPv6, Unicode labels, punycode, trailing dots, and invalid input. Assert both the returned value and the product action it drives.
Test permission removal and enterprise policy. The extension should fail closed for security decisions and degrade clearly for convenience grouping. It should not silently return the original hostname and pretend that parsing succeeded.
Do not turn a site boundary into an identity boundary
A registrable domain is useful for grouping, but it does not prove that two tabs share an account, owner, tenant, or security policy. A hosted platform can place unrelated customers below one registrable domain, while one company can operate several registrable domains.
Keep authentication and authorization on application identifiers, verified origins, or server-issued tenant data. Use the suffix result to organize UI, scope a convenience rule, or warn about a broad request. Do not use it as the only test for trusted messaging, credential sharing, or data access.
Review privacy impact before storing domain histories. Many extensions only need the current grouping key in memory or a hashed preference keyed to a user-created rule. A permanent list of visited registrable domains can become browsing history even when full URLs never leave the browser.
When telemetry is necessary for rollout, count result classes and failures rather than raw hostnames. Record API available, known suffix, unknown suffix, IP, invalid input, fallback used, or behavior mismatch. That evidence can expose migration risk without collecting the sites a person visited.
Set a deletion window for that aggregate evidence and keep domain examples inside a synthetic test corpus.
Our Chrome 153 compatibility checklist covers the faster release cadence. The FedCM multi-domain guide handles identity across related sites. Browse the Web hub, then audit preloading with the Speculation Rules guide.
