# Live widget

> Embed a live visitor count, a per-minute chart and your top countries, pages or referrers on your own site.

Source: https://metricraven.com/docs/live-widget  
Markdown: https://metricraven.com/docs/live-widget.md  
Section: Features

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.

> **Live example:** the demo site's widget runs on the [web version of this page](https://metricraven.com/docs/live-widget).

## 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](https://metricraven.com/docs/share-embed).

## Snippets

### Script (recommended)

```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.

| Attribute | What it does |
| --- | --- |
| data-widget | The widget token. Required. |
| data-target | A CSS selector to place the widget in, instead of next to the script tag. |
| data-theme | light, dark or auto: overrides the saved theme, for pages with their own light/dark switch. |
| data-max-width | Maximum width (default 360px). The widget fills narrower containers. |
| data-title | The iframe's accessible title (default "Live visitors"). |

```html title="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

```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

| Option | Choices | Default |
| --- | --- | --- |
| Window | Last 5, 30 or 60 minutes | 30 minutes |
| List | Top countries (with flags), top pages, top referrers or no list | Top countries |
| Theme | Auto (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 |
| Accent | Your dashboard theme's accent, one of its chart colours, or any colour | Theme accent |
| Size | Standard (five rows) or compact (three rows) | Standard |
| Corners | Rounded, square or extra round | Rounded |
| Title | Shown 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](https://metricraven.com/docs/realtime). 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.

```bash
curl https://metricraven.com/api/v1/widget/demo
```

```json title="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
}
```

| Field | Meaning |
| --- | --- |
| visitors | Unique 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. |
| title | The title to show, or null when it is hidden. |
| window, list, mode, size, radius, palette, branding | The saved options, with the colours to use per mode. |
| refreshSeconds | How 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](https://metricraven.com/docs/api-overview#fields).

## Content Security Policy

If your site sends a [Content-Security-Policy](https://metricraven.com/docs/content-security-policy), allow metricraven.com as a frame source, and as a script source for the script snippet:

```text title="Content-Security-Policy"
script-src https://metricraven.com;   # only for the script snippet
frame-src https://metricraven.com;
```

> **Note:** 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.
