mikeckennedy / umami-python

Umami Analytics Client for Python

Umami Analytics Client for Python

Client for privacy-preserving, open source Umami analytics platform based on httpx and pydantic.

umami-analytics is intended for adding custom data to your Umami instance (self-hosted or SaaS). Many umami events can supplied directly from HTML via their data-* attributes. However, some cannot. For example, if you have an event that is triggered in your app but doesn't have a clear HTML action you can add custom events. These will appear at the bottom of your Umami analtytics page for a website.

One example is a purchase-course event that happens deep inside the Python code rather than in HTML at Talk Python Training. This is what our events section looks like for a typical weekend day (US Pacific Time):

Focused on what you need, not what is offered

The Umami API is extensive and much of that is intended for their frontend code to be able to function. You probably don't want or need that. umami-analytics only covers the subset that most developers will need for common SaaS actions such as adding custom events. That said, PRs are weclome.

Core Features

• ➕ Add a custom event to your Umami analytics dashboard.
• 🌐 List all websites with details that you have registered at Umami.
• 🔀 Both sync and async programming models.
• ⚒️ Structured data with Pydantic models for API responses.
• 👩‍💻 Login / authenticate for either a self-hosted or SaaS hosted instance of Umami.
• 🥇Set a default website for a simplified API going forward.

See the usage example below for the Python API around these features.

Async or sync API? You choose

🔀 Async is supported but not required for your Python code. For functions that access the network, there is a func() and func_async() variant that works with Python's async and await.

Installation

Just pip install umami-analytics

Usage

import umami

umami.set_url_base("https://umami.hostedbyyouorthem.com")

# Auth is NOT required to send events, but is for other features.
login = umami.login(username, password)

# Skip the need to pass the target website in subsequent calls.
umami.set_website_id('cc726914-8e68-4d1a-4be0-af4ca8933456')
umami.set_hostname('somedomain.com')

# List your websites
websites = umami.websites()

# Create a new event in the events section of the dashboards.
event_resp = umami.new_event(
    website_id='a7cd-5d1a-2b33', # Only send if overriding default above
    event_name='Umami-Test',
    title='Umami-Test', # Defaults to event_name if omitted.
    hostname='somedomain.com', # Only send if overriding default above.
    url='/users/actions',
    custom_data={'client': 'umami-tester-v1'},
    referrer='https://some_url')

# Create a new page view in the pages section of the dashboards.
page_view_resp = umami.new_page_view(
    website_id='a7cd-5d1a-2b33', # Only send if overriding default above
    page_title='Umami-Test', # Defaults to event_name if omitted.
    hostname='somedomain.com', # Only send if overriding default above.
    url='/users/actions',
    referrer='https://some_url')

# Call after logging in to make sure the auth token is still valid.
umami.verify_token()

This code listing is very-very high fidelity psuedo code. If you want an actually executable example, see the example client in the repo.

Want to contribute?

See the API documentation for the remaining endpoints to be added. PRs are welcome. But please open an issue first to see if the proposed feature fits with the direction of this library.

Enjoy.

umami-python's Issues

Support IP address in new_event and new_page_view payloads

There is a potential PR for Umami to support adding an IP address to the payload for server side applications to forward the IP address. Obviously this would be perfect for this project, so looking forward to this going through:

umami-software/umami#2479

Support setting UA

Per the contributor instructions, just wanted to open an issue for this instead of directly sending PR.

Currently the UA is a hard coded string from a Macintosh computer:
event_user_agent = 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:121.0) Gecko/20100101 Firefox/121.0'

Which renders like this on Umami dashboard:

Since there is already a pretty low fidelity of information for the server side data, I think it would be helpful to allow forwarding the header information. Not everyone will have this, but some may.

One thing to be wary of is:
umami-software/umami#1833

This is needed to prevent bot detection check that prevents the request from being tracked in case we don't pass a user agent
You can also set DISABLE_BOT_CHECK=true in your umami environment to disable the bot check entirely:
https://github.com/umami-software/umami/blob/7a3443cd06772f3cde37bdbb0bf38eabf4515561/pages/api/collect.js#L13

We will also need a similar warning either way.

Add enabled/disabled flag

I think it would be nice to have an option to disable all events and page views. This way in dev and testing, if you're not wanting to trigger events but also don't want to change how you're using the API, just turn it off at app startup.

Why does umami-python need for username and Password

Hello, awesome project, I've been thinking about something similar for several server applications I run for mobile apps or games, so I'm definitely looking forward to adding this.

I didn't see a discussion section, so please let me know if there is somewhere better to move this conversation.

Why does umami-python need to use the login username and password for calling events? My limited Umami experience is that it is a small js snippet added to pages, which only contains my resource ID.

Why would this need more information in order to authenticate?

Blocking/Timeouts

This is a great project @mikeckennedy.

Are any of the calls to an umami server blocking with a timeout? Just curious if it would be better for me when integrating into an application, to move all these calls into an asychronous portion of the code to prevent sychronous web apis to hang in case the umami server is slow.