Features

Live widget

On this page

Show visitors on your own site: a live count for the last 5, 30 or 60 minutes, a bar for every minute and a short list of top countries, pages or referrers. It shows totals only, never who your visitors are.

The live widget for the demo site, refreshing every 20 seconds.

Turn it on

  1. Open Settings → General → Live widget

    Admins and the owner can switch on Public live widget. It is off for every new website.

  2. Pick the options

    The preview next to the options updates as you change them. Save options applies them to embedded widgets within a minute.

  3. Paste a snippet

    Copy the script or the iframe snippet into your page where the widget should appear. Each widget has its own token (wdg_…), separate from your share link.

Snippets

Script (recommended)

index.html
<script async src="https://metricraven.com/js/widget.js" data-widget="YOUR_WIDGET_TOKEN"></script>

The script adds the widget's iframe right where the tag is and keeps it as tall as the widget, so changing the size, list or title in Settings needs no new snippet. It is about 1 KB and loads asynchronously.

AttributeWhat it does
data-widgetThe widget token. Required.
data-targetA CSS selector to place the widget in, instead of next to the script tag.
data-themelight, dark or auto: overrides the saved theme, for pages with their own light/dark switch.
data-max-widthMaximum width (default 360px). The widget fills narrower containers.
data-titleThe iframe's accessible title (default "Live visitors").
index.html
<div id="live-visitors"></div>
<script async src="https://metricraven.com/js/widget.js"
  data-widget="YOUR_WIDGET_TOKEN"
  data-target="#live-visitors"
  data-theme="dark"
  data-max-width="320px"></script>

Plain iframe

index.html
<iframe src="https://metricraven.com/widget/YOUR_WIDGET_TOKEN" title="Visitors in the last 30 minutes"
  style="display:block;width:100%;max-width:360px;height:354px;border:0;border-radius:12px;overflow:hidden"
  loading="lazy" scrolling="no"></iframe>

For site builders that accept an iframe but not scripts. Its height matches the options you saved, so copy it again from Settings after changing the size, the list, the title or the corners. Add ?theme=light, ?theme=dark or ?theme=auto to the URL to override the theme.

Why an iframe

Both snippets render the widget in an iframe on metricraven.com. Your page's CSS can't break the widget and the widget's CSS can't leak into your page, it never runs code in your page's context besides the small loader, and it needs no cookies. The loader only accepts size messages from the exact frame it created.

Options

OptionChoicesDefault
WindowLast 5, 30 or 60 minutes30 minutes
ListTop countries (with flags), top pages, top referrers or no listTop countries
ThemeAuto (each visitor's light or dark preference), light, dark, or your dashboard theme's colours (light or dark per visitor; the MetricRaven theme on Starter)Auto
AccentYour dashboard theme's accent, one of its chart colours, or any colourTheme accent
SizeStandard (five rows) or compact (three rows)Standard
CornersRounded, square or extra roundRounded
TitleShown or hidden, with your own text (up to 60 characters)"Visitors in the last 30 minutes"

The count is unique visitors with a pageview or browser event in the window, and each bar is the unique visitors in that minute, counted like the realtime view. Countries count each visitor once, where they were last seen. Pages count unique visitors per page. Referrers count where each visitor's first pageview in the window came from.

Privacy

  • The widget only receives totals: a count, one number per minute and the top rows. It never contains visitor IDs, names, emails, cities, devices or exact times.
  • Pages are shown without query strings or fragments, and referrers as domains. Choose the countries list, or no list, if page paths on your site are private.
  • Anyone can send tracking events, so the widget only shows labels that can't carry a message: referrer domains, short campaign tags (letters, digits, dots, dashes) and plain paths of up to six short segments and 80 characters. Anything else is counted as Other.
  • Small numbers are shown as they are. The widget is off until you turn it on, it can only show the totals listed above, and a count of 1 can't be linked to a person without the IDs and times the widget never has. On a site with very little traffic, prefer the countries list.
  • Anyone who can see a page with the widget can read its totals. To stop that, choose Turn off widget or replace its link: the old token stops working at once, and embedded copies hide themselves.
  • The widget sets no cookies and doesn't track the people who view it.

Read the data yourself

GET /api/v1/widget/WIDGET_TOKEN returns the widget's data as JSON, to draw your own. It is public: no key, any origin (CORS *), read-only. demo is the demo site's widget.

terminal
curl https://metricraven.com/api/v1/widget/demo
Response
{
  "window": 30,
  "title": "Visitors in the last 30 minutes",
  "list": "countries",
  "mode": "auto",
  "size": "standard",
  "radius": "rounded",
  "palette": {
    "light": { "surface": "#FFFFFF", "ink": "#171B24", "muted": "#6B7280", "border": "#E5E7EB", "accent": "#14B8C8" },
    "dark": { "surface": "#151922", "ink": "#E7EAF0", "muted": "#98A1B2", "border": "#2A3040", "accent": "#38D9E6" }
  },
  "branding": true,
  "visitors": 42,
  "series": [
    { "minute": "2026-11-03T09:31", "visitors": 3 },
    { "minute": "2026-11-03T09:32", "visitors": 0 }
  ],
  "rows": [
    { "label": "US", "code": "US", "visitors": 14 },
    { "label": "GB", "code": "GB", "visitors": 6 }
  ],
  "generatedAt": "2026-11-03T10:00:12.401Z",
  "refreshSeconds": 20
}
FieldMeaning
visitorsUnique visitors in the last window minutes.
series[]One entry per minute, oldest first: minute (UTC, YYYY-MM-DDTHH:mm) and visitors.
rows[]Up to five rows (three when compact), most visitors first: label (country code, path or referrer domain), code (country code or null) and visitors. Empty for no list.
titleThe title to show, or null when it is hidden.
window, list, mode, size, radius, palette, brandingThe saved options, with the colours to use per mode.
refreshSecondsHow often to refresh (20).
  • Answers are cached for 5 seconds, so every viewer of a busy page shares one computation.
  • Each viewer can make 60 requests a minute per widget; beyond that the endpoint returns 429 with Retry-After.
  • A widget that is off, or whose link was replaced, returns 404.
  • Also supports fields, like every GET endpoint.

Content Security Policy

If your site sends a Content-Security-Policy, allow metricraven.com as a frame source, and as a script source for the script snippet:

Content-Security-Policy
script-src https://metricraven.com;   # only for the script snippet
frame-src https://metricraven.com;
The widget is included on every plan and shows a small “Analytics by MetricRaven” badge. On a paid Growth plan you can hide it in Settings → General → Share & embed; the free trial can't.

Details

  • The widget refreshes every 20 seconds, pauses while its tab is hidden and backs off after errors.
  • The visitor count is a polite live region: screen readers announce new counts without interrupting. The chart has a text summary, and every bar shows its minute and count on hover.
  • With reduced motion turned on, the live dot glows slowly instead of pulsing.
  • Times on the chart are in each viewer's own time zone.