Dashboard
Embed widgets
Put a small live card with your visitor numbers on a page of your own website, choose its colour and theme, and switch it off again.
This page shows how to place a small live card with your visitor numbers on your own website, for example in a footer or on an "open numbers" page, and what happens to the cards when you change or switch them off.
The two widgets #
There are two widgets, and both are small cards that fit in a sidebar or a footer.
| Widget | What it shows |
|---|---|
| Chart | The number of visitors in the last hour, a small trend line of that hour, and the countries with the most visitors. |
| Realtime | The number of people on the site right now, next to a dot that pulses while the card is live. |
"Right now" means the same as on the Realtime screen: activity in the last 2 minutes.
A widget shows its numbers to anyone who can see the page you put it on. It shows those numbers and nothing else: no pages, no sources, no revenue, and no way into the dashboard.
Switch them on #
Owners and Admins manage the widgets.
- Open the site and go to Settings, Sharing.
- Scroll to the Widgets section, below the public dashboard link.
- Switch on "Enable embed widgets". The widgets are on at once, with the colour, theme and expiry the section shows.
One switch turns on both widgets. They are separate from the shared dashboard link: either can be on without the other, and each has a token of its own. The token of the widgets cannot open the dashboard, and the dashboard link cannot open a widget.
Copy the embed code #
Once the widgets are on, the same section shows a preview of each widget and, under "Preview and embed code", the code to paste. Use the Chart and Realtime tabs to switch between the two.
Clear Saga writes the code for your site, with your token, your colour and your theme in it. Copy it from the card with its copy button and paste it into your page at the spot where the card should appear. Do not type it by hand or reuse the code of another site.
The code has two parts:
- A frame that loads the widget from Clear Saga. Your page and the widget stay separate: the widget cannot read your page.
- A small helper script,
embed.js. Its only job is to make the frame as tall as the card inside it. The widget reports its own height and the script sets it. It reads nothing else from your page and sends nothing anywhere. If your site blocks the script, the widget still appears, at the height it starts with.
The card has a fixed largest width and is narrower on a small screen.
Colour, theme and expiry #
The section has three settings. Change them and click Save. The preview shows a colour or theme while you try it, and the code changes when you save.
| Setting | Choices | What it does |
|---|---|---|
| Chart colour | One of the swatches, or any colour typed as six hex digits | Colours the trend line and the live dot. |
| Theme | Light, Dark or System | The background and text of the card. System follows the device of whoever views your page. |
| Link expiry | Never, or after 7, 30 or 90 days | Counted from the moment you save. After it the widgets show a dash until you save again. |
These are all the styling options there are. The size of the text, the shape of the card and what it shows are fixed.
How fresh the numbers are #
A widget asks for new numbers every 30 seconds while its page is visible, and pauses while the browser tab is hidden. An answer is reused for up to 15 seconds, so two people looking at the same page may see numbers that differ by a moment.
A widget page sets no cookies and does not count as a visit to your site. Search engines are told not to list it. A widget shows totals only: nothing of the live visitor card or of returning visitors reaches it, whatever the site has switched on.
Regenerate the token #
"Regenerate" in the Widgets section makes a new token, for when you want every placed widget to stop.
Switch them off #
Switch "Enable embed widgets" off and confirm. Placed widgets show a dash within about a minute. Your colour and theme are remembered for next time, but switching the widgets on again creates a new token, so the code has to be pasted again.
A widget that shows a dash is not broken on your page. The card stays in place, with a dash where the number was.
When the workspace is locked #
Widgets close while the dashboards of the workspace are locked, for example after a trial ended without a plan. They show a dash until the lock lifts, and then work again with the same code. Plans, usage and limits explains when that happens.
A widget shows a dash #
Check these, most likely first:
- The widgets were switched off, or the token was regenerated after the code was pasted. Copy the code again.
- The token expired. Open Settings, Sharing and save the Widgets section again.
- The workspace is locked.
- The code was cut short when it was pasted. Paste the whole of it.
Widgets through the API #
A program can read the embed code of a site with the embeds.get operation, which answers the code of both widgets, the token, the colour, the theme and the expiry. Switching widgets on or off, changing them and regenerating the token are done in the dashboard only. See the embed operation.
Next: Shared dashboards, Realtime, Managing a site