Skip to main content

Umami smart home integration, free and open source

Umami integration for Gladys Assistant

Visitors right now and today's visits of your Umami websites in Gladys, with a scene on a spike.

View on GitHubAll integrations

Umami is a simple, privacy-focused web analytics tool, open source (MIT), self-hosted or on Umami Cloud. This integration brings the figures of your Umami websites into Gladys: each website becomes a device with its visitors right now and its visitors, visits, page views, bounce rate and most viewed page of the day. Scenes can react to a visitor spike, to the first visitor of the day, or to a website that receives no visit any more (a broken tracking script), a dashboard widget shows the day at a glance, and a scene action puts the figures of a website in a message.

Tested against a real self-hosted Umami 3.4.0 and 2.19.0 (Docker, PostgreSQL); not yet on Umami Cloud: feedback welcome on the issues.

What you need​

  • Gladys Assistant 5.1.0 or later.
  • An Umami: on Umami Cloud, or your own server (Umami 2 or 3), reachable from the Gladys machine.
  • To sign in, one of:
    • Umami Cloud: an API key;
    • your own server, Umami 3.4 or later: an API key (it starts with umami_);
    • your own server, any version: a user name and its password. A user with the "view-only" role is enough, and the account must not use two-factor login.

At each refresh the integration sends two requests per website (visitors right now, figures of the day), plus the most viewed page every 5 minutes, the visits of the last hours every 15 minutes and the website list every 10 minutes. On Umami Cloud (50 requests per 15 seconds), the integration slows itself down to 40 requests per 15 seconds: with many websites, choose a longer interval so each read stays on time. Gladys accepts 300 states per minute: with the 30-second interval, add 25 websites at most to Gladys.

Getting started​

1. Create an API key, or a user​

  • Umami Cloud, or your server from Umami 3.4: in Umami, open Settings → API keys, create a key and copy it (it is shown only once).
  • Otherwise: in Settings → Users, create a user with the View only role and give it access to the websites (or use your own account).

2. Configure the integration​

In Gladys, open Integrations → Umami → Configuration:

  • Umami address: empty for Umami Cloud, or the address of your server (for example http://192.168.1.10:3000). An address copied from the browser is understood.
  • API key, or User name and Password: see above. With an API key, the user name and password are not used.
  • Refresh interval: from 30 seconds to 5 minutes (1 minute by default).
  • Visitor spike from: the visitors at the same time that fire the "Visitor spike" trigger (10 by default).
  • No visit for (hours): the hours without any visit that fire the "No visit for a while" trigger (24 by default).
  • Language of the names: language of the feature names and of the scene results (French by default).

Save, then click Test the connection: the result gives the number of websites, the visitors of the day and the visitors right now.

3. Add the websites​

Open the Discover tab: each website is proposed with its name. Add the ones you want to see in Gladys. The scene triggers and the widget work for every website, added or not.

The devices​

Each website becomes a device with:

  • Visitors right now: the visitors of the last 5 minutes, as in the "Realtime" page of Umami.
  • Visitors today: unique visitors since midnight.
  • Visits today: visits (sessions) since midnight.
  • Page views today: page views since midnight.
  • Bounce rate today: the share of visits that saw a single page, in percent.
  • Most viewed page today: its path, for example /posts/hello; "-" before the first page view of the day.

"Today" starts at midnight in the time zone of Gladys: the daily figures go back to 0 at midnight. A value that does not change is sent again every 12 hours, so Gladys keeps it recent.

Dashboard​

The Umami today widget shows four tiles (visitors right now, visitors, visits and page views of the day), added up over the websites shown, then one row per website with its visitors of the day and right now, the busiest first. With a single website, the most viewed page of the day is shown instead. In the widget settings, choose some websites to show only them (devices added to Gladys). The Refresh button reads Umami again.

Scenes​

Triggers​

  • Visitor spike: the visitors right now of a website reach the threshold of the configuration. Once per spike, and 30 minutes at least between two announcements for a website: a spike still under way at the end of the pause is announced then. Variables: website name, domain, visitors right now, threshold.
  • First visitor of the day: a website receives its first visitor since midnight. Variables: website name, domain, visitors today. If the integration was stopped, the first visitor is announced at the first read after it starts again.
  • No visit for a while: a website that had visits receives none for the hours of the configuration: the tracking script may be broken, or the website down. Once, until a visit comes again. Variables: website name, domain, hours without a visit.

Each trigger can be limited to some websites (empty: any). What the triggers remember is kept in the /data volume: a restart of Gladys or of the integration does not announce a spike or a first visitor twice. Nothing is announced at the first read of a website: a spike or a silence already under way is only recorded.

Actions​

  • Read the figures of a website: gives the name, the visitors right now (active), the visitors, visits, pageviews and bounce_rate of the day, the top_page, and a ready-made sentence, for example "Blog: 132 visitor(s) and 410 page view(s) today, 4 right now, most viewed page /posts/hello.".

Scene ideas​

  • When Visitor spike fires for your shop, send a Telegram message "Rush on {{website}}: {{visitors}} visitors right now".
  • When No visit for a while fires, send a notification "No visit on {{website}} for {{hours}} h: check the tracking script".
  • Every evening at 21:00, Read the figures of a website and send the sentence by message.
  • With the device feature Visitors right now as a scene condition, light a lamp in green while someone is on the website.

Troubleshooting​

  • "Umami Cloud: paste your API key": the address is empty, so the integration uses Umami Cloud. Fill in the address of your server if you host Umami yourself.
  • "API key, user name or password refused": copy the key again, or check the user name and password by logging in to Umami with them.
  • "this account uses two-factor login": create an API key (Umami 3.4+), or a dedicated view-only user without two-factor login.
  • "no Umami at this address": check the address and the port (3000 by default). Behind a reverse proxy with a sub-path (BASE_PATH), include it.
  • "the address redirects": enter the https:// address directly.
  • "too many requests": choose a longer refresh interval.
  • A website is missing: the user or the key must have access to it (websites of a team included). The list is read again every 10 minutes, or with Search in the Discover tab.
  • The logs of the integration (Integrations → Umami) say more; nothing is written there during a normal reading cycle.

Limits​

  • Read-only: the integration does not change anything in Umami.
  • The figures are those of Umami at the time of the read, with the refresh interval as delay. "Visitors right now" is the 5-minute window of Umami.
  • One Umami account (Cloud or server) per integration.
  • The thresholds of "Visitor spike" and "No visit for a while" are the same for every website.
  • Umami 1 is not supported (its API is different). The websites of a team are read from Umami 3; on Umami 2, only the ones the account owns or the teams it owns or manages.
  • Not tested on Umami Cloud yet, and not affiliated with Umami Software.

Configuration settings​

These are the settings Umami asks for in its configuration screen in Gladys.

SettingTypeRequiredDescription
Your Umami accountsectionNoUmami Cloud: leave the address empty and paste an API key (Settings → API keys). Your own server: its address, then an API key (Umami 3.4+) or a user name and password. Then add the websites from the Discover tab.
Umami addressstringNoEmpty for Umami Cloud, or the address of your own server.
API keysecretNoUmami Cloud, or your server from Umami 3.4 (it starts with umami_).
User namestringNoYour own server without an API key: a user that sees the websites (view-only is enough).
PasswordsecretNo
OptionssectionNo
Refresh intervalselectNoHow often Umami is read: two API requests per website each time.
Visitor spike fromnumberNoVisitors at the same time (last 5 minutes) that fire the scene trigger "Visitor spike".
No visit for (hours)numberNoHours without any visit that fire the scene trigger "No visit for a while".
Language of the namesselectNoLanguage of the feature names (set when a device is added) and of the scene results.

How to install Umami in Gladys​

  1. In Gladys, open Integrations: Umami appears in the catalog, next to the native integrations, with a community badge.
  2. Click Install. Gladys pulls the Docker image (ghcr.io/guim31/gladys-umami:1.0.0), starts it in a sandbox isolated from the core, and generates the integration's interface (devices, discovery and configuration).
  3. Open the Configuration screen of the integration, fill in the settings, and save.
  4. You can also install it directly from its repository URL: https://github.com/guim31/gladys-umami.

Umami requires Gladys >=5.1.0. The catalog inside Gladys refreshes every hour, so a new version becomes available at most one hour after its release.

Not running Gladys yet? It is free and open source: follow the installation guide to get started.

About external integrations​

Umami is an external integration: a community integration packaged as a Docker container and published on GitHub, that Gladys installs in one click and runs in a sandbox isolated from its core. It is published and maintained by guim31, not by the Gladys core team.

Subscribe to the Gladys Assistant newsletter

A few emails per month about new releases and project news. Sent by Pierre-Gilles Leymarie, founder of the project. Unsubscribe anytime 🙂
Last updated on