Download the PHP package matthiaswyler/kirby-live-visitors without Composer
On this page you can find all versions of the php package matthiaswyler/kirby-live-visitors. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download matthiaswyler/kirby-live-visitors
More information about matthiaswyler/kirby-live-visitors
Files in matthiaswyler/kirby-live-visitors
Package kirby-live-visitors
Short Description Display live visitor presence on your Kirby site using Plausible Analytics real-time data
License MIT
Homepage https://github.com/matthiaswyler/kirby-live-visitors#readme
FAQ
Example:
In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
- Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
- To use Composer is sometimes complicated. Especially for beginners.
- Composer needs much resources. Sometimes they are not available on a simple webspace.
- If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
- Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Informations about the package kirby-live-visitors
Kirby Live Visitors
Display live visitor presence on your Kirby site using real-time data from Plausible Analytics, combined with a lightweight server-side presence layer.
Shows individual visual elements (dots) for each live visitor, with location-based coloring and smooth enter/exit animations. Privacy-first by design — no cookies, no client-side storage, no personal data stored at rest.
Requirements
- Kirby 5+ (tested with Kirby 5)
- PHP 8.1+
- Plausible Analytics account with a Stats API key
Installation
Download
Download and copy this folder to site/plugins/kirby-live-visitors.
Git submodule
Composer
Setup
1. Get a Plausible Stats API Key
- Log into your Plausible account
- Go to Settings → API Keys
- Create a new Stats API key
2. Configure the Plugin
Add to your site/config/config.php:
The siteId defaults to your site's hostname. Override it if your Plausible domain differs:
3. Add the Snippet
Include the snippet in your template or layout, ideally before </body>:
The snippet renders nothing for logged-in Panel users or on the error page.
Configuration Options
| Option | Default | Description |
|---|---|---|
apiKey |
null |
(Required) Plausible Stats API key |
siteId |
auto-detected | Plausible site domain. Defaults to the Kirby site hostname |
baseUrl |
https://plausible.io |
Plausible instance URL. Change for self-hosted |
interval |
30 |
Frontend polling interval in seconds |
cacheTtl |
1 |
Server-side Plausible cache TTL in minutes |
presenceTtl |
30 |
Seconds a heartbeat keeps a visitor "present" |
activeTimeout |
60 |
Seconds after the last interaction a visible tab still counts as active |
dimensions |
['visit:country_name', 'visit:city_name'] |
Plausible dimensions for visitor breakdown |
Available Dimensions
You can configure which Plausible dimensions to query:
visit:country_name— Visitor countryvisit:city_name— Visitor cityvisit:region_name— Visitor regionevent:page— Current page pathvisit:device— Device type (Desktop, Mobile, Tablet)visit:browser— Browser namevisit:os— Operating system
Example with more dimensions:
Self-Hosted Plausible
Styling
The widget uses CSS custom properties for easy theming. Override them in your stylesheet:
Dark mode is supported automatically via prefers-color-scheme. Override for custom dark mode:
How It Works
The plugin combines two sources into a single live count:
- Plausible realtime — the route proxies Plausible's Stats API v2 (
date_range: "realtime", last 5 min) and caches the aggregate response server-side to respect rate limits. - Presence — the frontend sends a small
heartbeatevery 15s. The heartbeat fires only while the tab is visible and the visitor has interacted withinactiveTimeoutseconds, so idle/background/kiosk tabs are not counted. The server derives a presence id and keeps the visitor "present" forpresenceTtlseconds. This gives immediate, per-visitor dots even before Plausible's realtime figures update. - The reported total is
max()of the two, so a visitor is never double-counted.
Presence Identity (no client storage)
The heartbeat carries no client-side identifier. Instead, the server derives a stable presence id:
- Raw IP addresses and User-Agent strings are never stored — only the truncated hash is written to the presence file.
- The salt is random and rotates every day, so ids are non-reversible and cannot be correlated across days.
- Because the id is derived from IP + User-Agent, multiple tabs and reloads from the same visitor collapse into a single presence entry (this fixes the common "one visitor counted per tab" inflation).
- Known bots/crawlers are filtered out by User-Agent before any processing.
This is the same salted-hash technique Plausible uses for its own visitor counting.
Privacy & GDPR
This plugin is designed to be deployable without a consent banner:
No Cookies, No Client-Side Storage
The plugin sets no cookies and writes nothing to localStorage or sessionStorage. Since nothing is stored on or read from the visitor's device for this feature, the ePrivacy Directive's consent requirement for device storage does not apply.
Personal Data
- Plausible data is fully aggregate (e.g. "3 visitors from Zurich") and privacy-first — Plausible uses no cookies, no fingerprinting, and stores no PII.
- Presence briefly processes the visitor's IP and User-Agent server-side only to derive a non-reversible, daily-rotating hash. The raw IP and User-Agent are never persisted. Only the truncated hash, the current page path, and a timestamp are stored, in a short-lived JSON file that is purged automatically (default: entries expire after 30s of inactivity and are pruned within 120s).
Under GDPR, this transient processing to produce a pseudonymised, non-reversible identifier — with no cross-day correlation and no cookies — rests on legitimate interest (showing live presence), consistent with the widely accepted legal basis for privacy-first analytics like Plausible.
Not legal advice. If your jurisdiction or DPA takes a stricter view, you can omit the snippet or reduce
presenceTtl.
Data Flow
- Plausible → Kirby: aggregate counts by dimension
- Browser → Kirby: a heartbeat containing only the current page path (no identifier)
- Stored at rest: a short-lived server cache (Plausible response) and a TTL-gated presence file (salted hash + page + timestamp)
Self-Hosted Plausible
If using self-hosted Plausible, the same guarantees apply and data never leaves your infrastructure.
Rate Limits
Plausible's Stats API has a default rate limit of 600 requests per hour. With the default 1-minute server-side cache, the plugin makes at most 60 requests per hour — well within limits regardless of how many visitors are polling the frontend.
License
MIT
