Configuration
All configuration lives on one whiteboard inside the umami module. There is no configuration file, no environment variable, and no client object to carry around. A handful of setter functions write on the whiteboard, usually once at startup, and every other function reads from it. This page lists what is on the whiteboard, what it says before you write anything, and who reads each line.
Settings
| Function | Sets | Default | Required by |
|---|---|---|---|
set_url_base(url) |
The instance root for self-hosted mode. Must start with http:// or https://. A trailing slash is removed. /api must not be included. |
none | Every call in self-hosted mode |
set_website_id(website_id) |
Default website for sending and querying. | none | Send functions, website_stats(), active_users() unless passed per call |
set_hostname(hostname) |
Default hostname recorded on events and page views. | none | Send functions unless passed per call |
set_cloud_api_key(key, region=None) |
Umami Cloud key and optional 'us' or 'eu' region. Switches to Cloud mode. |
none | Every call in Cloud mode |
| clear_cloud_api_key() | Removes the key and region. Back to self-hosted mode. | ||
login(username, password) |
Stores the token for query calls. Self-hosted only. | none | websites(), website_stats(), active_users(), verify_token() |
| enable() / disable() | Whether the send functions make requests. | enabled |
The setters are synchronous only. There is no set_url_base_async(), because writing on a whiteboard does not need an event loop.
Per-call defaults
The send functions fill in the session fields Umami expects from a browser, so an event from a Python process looks enough like a visit for Umami to file it. Override any of them per call.
| Argument | new_event | new_page_view | new_revenue_event |
|---|---|---|---|
url |
'/' |
required | '/' |
title |
the event name | page_title, required |
the event name |
referrer |
'' |
'' |
'' |
language |
'en-US' |
'en-US' |
'en-US' |
screen |
'1920x1080' |
'1920x1080' |
'1920x1080' |
ua |
not accepted | desktop Chrome user agent | not accepted |
ip_address |
not sent | not sent | not sent |
distinct_id |
not sent | not sent | not sent |
custom_data |
{} |
not accepted | {} plus revenue and currency |
event_name |
required | none | 'revenue' |
currency |
'USD' |
What happens on a second call
Whiteboards get overwritten, and the rules are short:
- set_url_base() again replaces the previous value.
- login() again replaces the stored token. There is no logout.
- set_cloud_api_key() again replaces the key and region.
- set_cloud_api_key() after login() switches to Cloud mode. The login token is kept but unused until clear_cloud_api_key().
- set_url_base() while a Cloud key is set stores the URL but it is ignored until clear_cloud_api_key().
- clear_cloud_api_key() when no key is set does nothing.
- enable() and disable() are idempotent.
Precedence
An explicit website_id or hostname argument on a call always wins over the value set with set_website_id() or set_hostname(). Passing None falls back to the default; passing an empty string is treated as missing and raises ValidationError.
Reading the current state
The public API has no getters. is_logged_in() tells you whether a token or Cloud key is present. For anything else, keep your own record of what you configured. If you are in a debugger, the module umami.impl holds the values as plain attributes (url_base, default_website_id, default_hostname, auth_token, api_key, cloud_region, tracking_enabled), which is handy for a quick look and in tests, but it is an implementation detail rather than a supported interface.
Version
umami.__version__ is read from the installed distribution metadata and is '0.0.0' when the package is imported from a source checkout that was not installed. umami.user_agent is the User-Agent sent on query calls and includes the version and Python version.