# Managed proxy

> Serve the MetricRaven script and events from your own subdomain with one CNAME record. MetricRaven handles routing and the certificate.

Source: https://metricraven.com/docs/managed-proxy  
Markdown: https://metricraven.com/docs/managed-proxy.md  
Section: Proxy

Route MetricRaven through a subdomain of your website without running any proxy code. You add one DNS record; MetricRaven serves the script and receives events there, with its own TLS certificate.

> **Note:** **Recommended for most sites.** Use the managed proxy unless your app already proxies requests through its own server. To compare both options, see [Serve tracking from your own domain](https://metricraven.com/docs/proxy).

## Why use a proxy?

Ad blockers often block known analytics domains. A subdomain of your own website is blocked less often, so you see more of your visits and more of your [revenue attribution](https://metricraven.com/docs/stripe). You don't need a proxy to start; add one before a launch or when you want more complete data.

Without a proxy, the script and its events go to `metricraven.com`. With the managed proxy they go to your subdomain instead, for example `a.example.com/js/script.js` and `a.example.com/api/v1/collect`.

## Set it up

1. **Enable the managed proxy**

   - Open **Settings → Tracking & install → Managed proxy** on your website's dashboard.
   - Enter a subdomain of your website, such as `a.example.com`, and select **Enable**.

   > **Note:** Pick a short, neutral name such as `a` or `cdn`. Blocklists often target names like `analytics`, `tracking`, `stats` or `metrics`. Use a subdomain, not your main site's hostname. Admins and the owner can set it up; each website has one managed proxy.

2. **Add the DNS record**

   The dashboard shows the exact record. For a subdomain it's one CNAME:

   | DNS field | Value |
   | --- | --- |
   | Type | CNAME |
   | Name / Host | `a` |
   | Target / Value | `proxy.metricraven.com` |
   | TTL | Auto (or 300 seconds) |
   | Proxy status | DNS only, proxy off (Cloudflare: grey cloud) |

   The dashboard looks up where your domain's DNS is hosted and, for the providers below, shows that provider's steps, its own field names, a link to its DNS page and a copy button for each field.

   `a` is only an example: for `cdn.example.com` the name is `cdn`. If the dashboard also shows a TXT record, add it only when the status stays on **Waiting for DNS** for more than 10 minutes. You can delete the TXT record once the proxy is active.

   DNS changes usually show up within 1–10 minutes. MetricRaven checks automatically (every minute at first) and issues the certificate as soon as the record is in place. Select **Check again** to look right away.

3. **Update your script tag**

   When the status is **Active**, replace your MetricRaven tag with this one. The Install card in Settings shows it with your site ID filled in.

   ```html title="Your website's shared layout"
   <script defer src="https://a.example.com/js/script.js" data-site-id="YOUR_SITE_ID"></script>
   ```

   The tracker sends its events to the host it was loaded from, so there's no separate events URL to set. If your tag has a `data-api` attribute from a self-hosted proxy, remove it.

## Steps by DNS provider

Add the record where your domain's DNS is hosted, which isn't always where you bought the domain. The dashboard detects it from your domain's nameservers. Field names differ by provider:

| Provider | Where | Name field | Target field | TTL | Proxy / forwarding |
| --- | --- | --- | --- | --- | --- |
| Cloudflare | DNS → Records → Add record | Name | Target | Auto | **DNS only (grey cloud)** |
| Amazon Route 53 | Hosted zones → your domain → Create record | Record name | Value | 300 | Alias off |
| Google Cloud DNS | Cloud DNS → your zone → Add standard | DNS name | Canonical name | 300 | Off |
| GoDaddy | Domain Portfolio → your domain → DNS → Add New Record | Name | Value | 1/2 Hour | DNS record, not forwarding |
| Namecheap | Domain List → Manage → Advanced DNS → Add New Record | Host | Value | Automatic | CNAME Record, not URL Redirect |
| Squarespace | Domains → your domain → DNS → DNS settings → Custom records | Host | Data | Default | Custom record, not forwarding |
| IONOS | Domains & SSL → your domain → DNS → Add record | Host name | Points to | 1 hour | DNS record, not forwarding |
| Vercel | Domains → your domain → DNS Records | Name | Value | 60 | Off |
| Netlify | Domains → your domain → DNS records → Add new record | Name | Value | 3600 | Off |
| DigitalOcean | Networking → Domains → your domain → CNAME | Hostname | Is an alias of | 300 | Off |
| Hetzner | Hetzner Console → project → DNS → your zone | Name | Value | Default | Off |

Any other provider works the same way: add a CNAME with the name and target from the dashboard, keep the default TTL, and keep any proxy, CDN, forwarding or redirect option off for this record.

> **Note:** **On Cloudflare, set Proxy status to DNS only (grey cloud).** With the orange cloud (Proxied), requests go through your own Cloudflare zone first and don't reach the MetricRaven proxy, so the status stays on Waiting for DNS or the subdomain returns errors. Turning the cloud grey fixes it within a few minutes; select **Check again**.

Why it matters: the record has to point straight at `proxy.metricraven.com`. The certificate for your subdomain is issued only once the name resolves there, and that's how requests to your subdomain reach MetricRaven.

## Statuses

| Status | Meaning |
| --- | --- |
| Waiting for DNS | The CNAME record isn't visible yet. The dashboard shows the last check's result. |
| Issuing certificate | DNS is correct and the TLS certificate is being issued, usually within a few minutes. |
| Active | The subdomain serves the script and receives events. Switch your tag now. |
| Needs attention | Something broke, for example the CNAME was removed or never appeared. The dashboard says what to fix. |

If no record appears within 7 days, MetricRaven stops checking and the status becomes **Needs attention**. Add the record and select **Check again** to start over. Active proxies are rechecked every few hours.

> **Verify it works**
>
> - Open your live website, not the proxy subdomain itself (its root page is a 404 on purpose).
> - In the browser's Network panel, `script.js` loads from your subdomain and events go to `https://a.example.com/api/v1/collect` with `ok: true`.
> - Your visit appears in the realtime view.

## Troubleshooting

| Problem | What to check |
| --- | --- |
| Status stays on Waiting for DNS | The CNAME matches the dashboard exactly; it's a DNS record, not a redirect or forwarding rule; your DNS provider's proxy mode (such as Cloudflare's orange cloud) is off for this record. Then wait a few minutes and select Check again. |
| Needs attention | Re-check the record's type, name and target. Make sure you're editing the DNS zone of your website's domain. Add the TXT record if the dashboard shows one. |
| Still blocked or not loading | Avoid obvious names (analytics, tracking, stats, metrics). The script src uses https:// and your subdomain, not metricraven.com. |
| Content Security Policy errors | Allow your proxy subdomain in script-src and connect-src. |
| Events refused with domain_not_allowed | The page sending them isn't one of your website's domains. The proxy subdomain doesn't need to be listed; the pages that load the script do. |

## Remove the managed proxy

First point your script tag back at `https://metricraven.com/js/script.js`. Then, in **Settings → Tracking & install → Managed proxy**, select **Remove**; the subdomain stops serving the script at once. Finally delete the DNS record.

## API, CLI and MCP

With an [account token](https://metricraven.com/docs/api-authentication) and `?site=` (changes need the write scope and an admin or the owner):

| Request | What it does |
| --- | --- |
| GET /api/v1/managed-proxy | Hostname, status, error, the DNS records to add and the script tag. |
| POST /api/v1/managed-proxy { "hostname": "a.example.com" } | Sets it up (201). 409 if the website already has one or the hostname is taken. |
| POST /api/v1/managed-proxy/check | Looks for the DNS record now. |
| GET /api/v1/managed-proxy/dns-provider | Where the subdomain's DNS is hosted: zone, nameservers and provider (or null). |
| DELETE /api/v1/managed-proxy | Removes it. |

CLI: `metricraven proxy status`, `proxy enable a.example.com`, `proxy check` and `proxy remove`. MCP: `get_managed_proxy`.

## Managed or self-hosted?

|  | Managed proxy | Self-hosted proxy |
| --- | --- | --- |
| Best for | Most sites | Apps that already proxy requests through their own server |
| Code required | No | Yes |
| DNS | One CNAME | None |
| TLS certificate | Handled by MetricRaven | Your host's |
| Script tag | src on your subdomain | src and data-api on your own paths |
| Maintenance | Handled by MetricRaven | Yours |

For self-hosted setups, see the [proxy recipes](https://metricraven.com/docs/proxy#recipes).

## Details

- The subdomain answers only the script and the events endpoint. Every other path is a 404.
- Only your website can send events through its subdomain, and events are still checked against your website's domains, as without a proxy.
- Visitor locations and per-visitor rate limits work as without a proxy: the visitor's IP is passed along.
- The script is cached for up to an hour, so tracker updates reach your subdomain within the hour.
- A proxy doesn't guarantee that every blocker will allow tracking.