Features
Private embed
On this page
Put the MetricRaven dashboard inside your own app, for example on an admin page your team already signs in to. The dashboard runs in an iframe; your server fetches each report with your site's secret key.
Only place the private embed behind your own sign-in. It shows more than a share link (see below), and your relay reads with a secret key, which can read everything the API offers. Anyone who can open the page and reach your relay sees what the embed shows. For a dashboard anyone may see, use a share link instead.
How it works
- Your admin page loads
https://metricraven.com/embed/YOUR_SITE_ID?parent=https://admin.example.comin an iframe. The iframe holds no MetricRaven session and no key, so it works with third-party cookies blocked. - For each report it posts a request to your page (
window.postMessage). Your page sends it to a relay route on your server, which checks your user's session, addsAuthorization: Bearerwith the secret key and returns MetricRaven's answer. - The page with the iframe must use HTTPS, and its hostname must be one of the website's domains or a subdomain of one (
admin.example.comforexample.com). Otherwise the embed answers 404 and refuses to be framed.
What it shows compared with a share link
Both show the Traffic, Revenue and AI visibility tabs with charts, filters, date ranges, comparisons and detail dialogs. The private embed also shows what is private to your team, unless you hide it:
| Item | Private embed | Share link |
|---|---|---|
| Online now and the realtime view | Yes | No |
| Visitor journeys, visitor lists and profiles | Yes | No |
| Names and emails of identified visitors and customers | Yes (generated avatars, no pictures) | No |
| Chart notes | Yes, read only | No |
| GitHub commits on the chart | Yes | No |
| Saved segments | Yes, can be applied | No (report filters only) |
| Settings | No | No |
| Changes (notes, segments, funnels, goals, settings) | No: read only | No: read only |
More about each: realtime, visitor explorer, chart notes, GitHub commits and saved segments.
Set it up
Create a secret key for the embed
In Settings → General → Share & embed, choose Private embed and select Create private embed. It creates a named key called "Private embed" and shows it once, with the two lines to store on your server. Or create one yourself in Settings → Tracking & install → Secret keys, with Add a named key (for example "Admin embed"), and copy it. Store it on your server only, for example as
METRICRAVEN_SECRET_KEY, next to your site ID (ana_pub_…, shown under the Install card in Settings → Tracking & install) asMETRICRAVEN_SITE_ID. A separate key shows its own last use and can be revoked without touching your other integrations. See API authentication.Add the relay route on your server
One POST route behind your admin sign-in. It forwards only the GET reports the dashboard needs, only for your site, and never sends the key to the browser:
server.js// POST /admin/metricraven: the relay behind the embedded dashboard (Node 18+, Express). const SITE_ID = process.env.METRICRAVEN_SITE_ID; // ana_pub_… const SECRET_KEY = process.env.METRICRAVEN_SECRET_KEY; // a named secret key const CHANNEL = "metricraven:private-embed:v1"; // The reports the embedded dashboard reads. It only ever sends GET. const READ = /^\/api\/v1\/(stats\/[a-z][a-z0-9-]{0,63}(\/[a-z][a-z0-9-]{0,63})?|visitors\/[A-Za-z0-9_-]{1,100}|site|funnels|segments|notes|commits|goals\/customizations)$/; function allowed(m) { if (m?.channel !== CHANNEL || m.type !== "request" || m.method !== "GET") return false; if (!/^[A-Za-z0-9_-]{1,80}$/.test(String(m.id)) || typeof m.url !== "string") return false; if (m.url.length > 20000 || /[\\#\r\n]/.test(m.url) || m.body !== undefined) return false; const url = new URL(m.url, "https://relay.invalid"); return ( url.pathname === m.url.split("?")[0] && READ.test(url.pathname) && url.searchParams.getAll("site").length === 1 && url.searchParams.get("site") === SITE_ID && !url.searchParams.has("share") ); } // requireAdmin is your own check: 401 unless the signed-in user may see analytics, // and 403 unless the request comes from your own origin (Origin / Sec-Fetch-Site). app.post("/admin/metricraven", requireAdmin, express.json({ limit: "100kb" }), async (req, res) => { res.set("Cache-Control", "private, no-store"); if (!allowed(req.body)) return res.status(400).json({ message: "Unsupported dashboard request." }); try { const upstream = await fetch("https://metricraven.com" + req.body.url, { headers: { Authorization: "Bearer " + SECRET_KEY }, redirect: "error", signal: AbortSignal.timeout(20000), }); res.status(upstream.status).json(await upstream.json().catch(() => ({}))); } catch { res.status(502).json({ message: "MetricRaven could not be reached." }); } });Add the iframe and the bridge to your admin page
The script answers the iframe's requests through your relay and sends your app's theme when the dashboard is ready:
admin page<iframe id="metricraven" title="Analytics" style="width:100%;height:1600px;border:0"></iframe> <script> const SITE_ID = "YOUR_SITE_ID"; const ORIGIN = "https://metricraven.com"; const CHANNEL = "metricraven:private-embed:v1"; const frame = document.getElementById("metricraven"); window.addEventListener("message", async (event) => { // Only this frame, from MetricRaven's exact origin. if (event.origin !== ORIGIN || event.source !== frame.contentWindow) return; const message = event.data; if (message?.channel !== CHANNEL) return; if (message.type === "ready") { frame.contentWindow.postMessage({ channel: CHANNEL, type: "theme", theme: "light" }, ORIGIN); return; } if (message.type !== "request" || message.method !== "GET") return; let status = 502; let data = { message: "Analytics could not be reached." }; try { const res = await fetch("/admin/metricraven", { method: "POST", credentials: "same-origin", headers: { "Content-Type": "application/json" }, body: JSON.stringify(message), }); status = res.status; data = await res.json().catch(() => ({})); } catch {} frame.contentWindow.postMessage({ channel: CHANNEL, type: "response", id: message.id, status, data }, ORIGIN); }); frame.src = ORIGIN + "/embed/" + SITE_ID + "?" + new URLSearchParams({ parent: location.origin, theme: "light" }); </script>parentmust be the exact origin of this page (including the port, if any). Usetheme=dark, or send a theme message whenever your app switches mode.Choose what it shows
In Settings → General → Share & embed, pick Private embed and untick what your app's users shouldn't see. The Reddit row at the bottom of the list adds the Reddit tab to the embed (drafted and posted replies, read-only). It is off until you tick it, and share links never show it. See Hide tabs, sections and cards.
Verify it works
- Open your admin page while signed in: the dashboard loads with your site's reports.
- In the Network panel, report requests go to your relay (
/admin/metricraven), never to MetricRaven with a key in the browser. - Signed out (or in a private window), the relay answers 401 and the dashboard shows no data.
Hide tabs, sections and cards
Settings → General → Share & embed → What to show has a Share link / Private embed switch, so the embed has its own choice, separate from the share link. Untick a tab (Traffic, Revenue, AI visibility) to hide all of it, or expand it to hide single sections, cards and tiles, such as Online now, Chart notes, GitHub commits or the Revenue tab's Customers. At least one tab stays shown. Each change is saved as you make it, and the embed applies it on its next load. Everything stays shown until you change it.
The embedded dashboard neither shows nor requests a hidden item. MetricRaven can't refuse those requests on its side, because your relay acts with a secret key. If some reports must never reach your app's users, also leave their paths out of your relay's READ list (for example stats/live or stats/visitors).
Troubleshooting
| What you see | What to check |
|---|---|
| The iframe shows Not found | parent is the exact HTTPS origin of the page, its hostname is one of the website's domains (or a subdomain), and the site ID is right. |
| Open this dashboard from your site's admin | The embed URL was opened directly. It only works inside an iframe on your page. |
| Your admin session has expired or access was denied | Your relay answered 401 or 403. Sign in to your app again, then reload. |
| The host did not respond | The bridge script isn't listening, or it checks a different origin than https://metricraven.com. |
| Downloads don't start | If your iframe has a sandbox attribute, add allow-downloads (the Details dialogs save CSV files). |
| The browser blocks the frame | Your Content Security Policy needs frame-src https://metricraven.com. |
Details
- The embed is read only: changes to notes, segments, funnels, goals and settings happen in MetricRaven, where each teammate's role applies. Its Manage settings in MetricRaven link opens Settings for signed-in members.
- The embed uses the site's dashboard theme. Its own light/dark button wins over theme messages until the iframe reloads.
- Rolling or revoking the key in Settings → Secret keys stops the embed until your server has the new key.