Get started
Domain ownership: verify your domain
On this page
A domain belongs to the account that proves it controls the website. Adding a domain to a site doesn't make it yours; verifying it does. Most sites are verified automatically, without you doing anything.
How verification works
A site verifies a domain in one of three ways. The first that works counts.
| Method | How |
|---|---|
| Page check (automatic) | When your site starts receiving visits from a domain nobody has verified yet, MetricRaven loads https://your-domain/ in the background and looks for your site ID (ana_pub_…) in the HTML. The install script carries it as data-website-id, so a normal install verifies itself within minutes. Installed through Google Tag Manager? When the page loads a GTM container (the official GTM snippet), we also read that container's public file at googletagmanager.com and look for your site ID there, so a GTM install verifies itself too. If it isn't found, we try again at most every 6 hours while visits keep arriving (every 10 minutes during a free trial). |
| DNS TXT record | For installs the page check can't see: other tag managers, server-side GTM, or a home page that blocks our checker. Add a TXT record named _metricraven.your-domain with the value shown in Settings → General → Site → Verify (it looks like metricraven-site-verification=…), then choose Check now. |
| Managed proxy | An active managed proxy on a subdomain of the domain counts as proof: its CNAME can only be added by whoever controls the domain's DNS. |
Settings → General → Site shows each domain as Verified (with the method), Not verified or Locked. Admins and the owner can open Verify on a domain that isn't verified to see the TXT record and run a check right away. Checks are limited to a few per website every 10 minutes.
Install the script on your home page
Follow Install & verify. Once a visit arrives, the page check runs on its own.
Another tag manager, or the check can't reach your page? Add the TXT record
Open Settings → General → Site, choose Verify next to the domain, copy the name and value into a TXT record at your DNS provider and choose Check now. DNS changes can take a few minutes to show.
What the page check fetches
- Only
https://your-domain/(orhttps://www.your-domain/when the bare domain doesn't answer), on port 443, with the user agentMetricRavenVerifier/1.0. - At most 3 redirects, and only within the domain and its
www.variant. At most 1 MB is read, with a 5-second timeout. No cookies or credentials are sent. - Addresses that aren't on the public internet (private networks, loopback, link-local) are never fetched.
- When the page loads Google Tag Manager, up to 3 of its containers from
https://www.googletagmanager.com/gtm.js?id=GTM-…(at most 3 MB, 8-second timeout). Only container IDs in the official GTM snippet or loader URL count, not one merely written in the page's text.
If your firewall or bot protection blocks unknown agents, allow MetricRavenVerifier or use the DNS record instead.
Adding a domain someone else has
You can add any domain that no other account has verified, from the home page, Add a site, Settings → General → Site, the API, MCP or CLI. Several accounts can list the same domain while nobody has verified it. A domain another account verified can't be added: the answer is 409 domain_taken ("verified by another MetricRaven account"). If you work on that website, ask its owner to invite you (Settings → Team), or add the site with its secret key under Add an existing site. MetricRaven never tells you which account verified it.
Domains are compared without www., case or port. Subdomains follow one rule: the most specific verified domain wins its hosts.
- Verifying
example.comcovers its subdomains: another account can't addapp.example.com(409 domain_taken, namingexample.com), and sites that already list one are locked like copies of the domain itself. - A subdomain verified on its own stays with whoever verified it, even if another account later verifies the parent. That account can still add deeper subdomains such as
api.app.example.com. - Listing a parent of someone else's verified subdomain is allowed (you may own
example.comwhile an agency verifiedapp.example.com), but that site doesn't collect from the verified subdomain or below it: those events get403 domain_locked. Settings → General → Site lists such subdomains under the domain, without saying who verified them. Everything else under the domain is collected as usual.
During the free trial
A free trial records visits, events, payments and crawler requests only from verified domains (local development on localhost and native apps excepted). Visits from a domain that isn't verified yet are answered with 403 domain_unverified and start a verification check, repeated every 10 minutes while they keep arriving, so recording usually starts within minutes of installing. The install check and Settings → General → Site show when visits are waiting for verification. Each domain gets one free trial: a domain another account already verified needs a plan.
When another account verifies your domain
If your site lists a domain that another account then verifies, your site's copy is locked:
- Events from that domain are refused for your site (
403 domain_locked). Its other domains keep collecting. - The dashboard shows a banner with the date, and the owner and admins get one email. Neither names the other account.
- Remove the domain before that date (the banner's Remove button, or Settings → General → Site) and the site is kept with its reports. If it was the site's only domain, add the domain you do run so it keeps collecting.
- After 14 days, a site that still lists the locked domain is deleted with all its data, the same way as deleting a website yourself.
Weekly re-check
Once a week, each verified domain is checked again with the method that verified it: your site ID on the home page, the TXT record, or an active managed proxy.
- One failed check changes nothing; we try again every day.
- After 14 days of failed checks in a row, the owner and admins get one email and the dashboard shows a notice: put the script or record back, or choose Verify again (any of the three methods counts).
- After 21 days, the domain is released. Your site, its domains and its data stay as they are and nothing is locked or deleted, but another account can then verify the domain.
- Any successful check ends the streak.
Your domain was verified by someone else
If another account verified your domain and you control the website, choose Verify again on the banner (or on the Locked domain in Settings → General → Site). We check your site's proof and the current owner's proof at that moment:
| Result | What happens |
|---|---|
| Yours passes, theirs fails | The domain moves to your site: your lock lifts, and the other account's copy is locked with the usual 14 days, banner and email. |
| Both pass | The domain stays where it is (for example an agency's and a client's script on the same page). Ask that site's owner to invite you. |
| Yours fails | Nothing changes. Put the install snippet on your home page, or add the TXT record, then try again. |
A domain that just changed hands can't be disputed back for 24 hours. Checks share the limit of Check now. Still stuck? Email support@metricraven.com.
API
| Endpoint | What it does |
|---|---|
| GET /api/v1/site/domains?site=SITE_ID | Each domain's state: verified (method, verifiedAt, and failingSince / releaseAfter while re-checks fail), verified_other_site, locked (with deleteAfter) or unverified. Admins and the owner also get the TXT value. |
| POST /api/v1/site/domains/verify?site=SITE_ID | Check now and Verify again, body { "domain": "example.com" }. result verified, verified_other_site or not_found; on a domain another account verified it is a dispute: transferred, both_verified or not_found, and 409 dispute_cooldown (with retryAfter) within 24 hours of a transfer. 429 rate_limited after 6 checks per website (20 per user) in 10 minutes. |
| POST /api/v1/site/domains/remove?site=SITE_ID | Removes one domain, body { "domain": "example.com" }. Unlike PUT /api/v1/site it may remove the last domain, which resolves a lock. |
These use a dashboard session or an account token (admins and the owner for changes), not the site secret key. See the site API for the rest of the settings.