Metadata-Version: 2.5
Name: streamlit_analytics2
Version: 0.11.0
Summary: Privacy-first usage analytics for Streamlit apps: pageviews, visitors, widget clicks, custom events, a built-in dashboard and SQL over your own data. No JavaScript, no cookies.
Project-URL: Repository, https://github.com/444B/streamlit-analytics2
Project-URL: Documentation, https://github.com/444B/streamlit-analytics2/wiki
Project-URL: Issues, https://github.com/444B/streamlit-analytics2/issues
Author-email: 444B <contact+pypi@444b.me>
License: MIT License
        
        Copyright (c) 2021 Johannes Rieke
        
        Copyright (c) 2024 444B
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: ai-agents,analytics,dashboard,event-log,gdpr,llm-apps,privacy,product-analytics,sqlite,streamlit,streamlit-analytics,streamlit-analytics2,telemetry,usage-tracking,web-analytics
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Database :: Front-Ends
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: >=3.10
Requires-Dist: altair>=5.5.0
Requires-Dist: google-cloud-firestore>=2.19.0
Requires-Dist: pandas>=2.2.3
Requires-Dist: streamlit>=1.47.0
Provides-Extra: dev
Requires-Dist: bandit>=1.8.0; extra == 'dev'
Requires-Dist: black>=24.10.0; extra == 'dev'
Requires-Dist: build>=1.2.2.post1; extra == 'dev'
Requires-Dist: flake8>=7.1.1; extra == 'dev'
Requires-Dist: isort>=5.13.2; extra == 'dev'
Requires-Dist: mypy>=1.14.0; extra == 'dev'
Requires-Dist: pandas-stubs>=2.2.3.241126; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=8.3.4; extra == 'dev'
Requires-Dist: twine>=6.0.1; extra == 'dev'
Provides-Extra: firestore
Requires-Dist: google-cloud-firestore>=2.19.0; extra == 'firestore'
Provides-Extra: test
Requires-Dist: pytest-cov>=4.0.0; extra == 'test'
Requires-Dist: pytest>=8.3.4; extra == 'test'
Description-Content-Type: text/markdown

# streamlit-analytics2

**Privacy-first usage analytics for Streamlit apps.** One `with` block gives
you pageviews, visitors, widget clicks, custom events, a built-in dashboard
and SQL over your own data. No JavaScript, no cookies, no IP addresses stored.

[![PyPI](https://img.shields.io/pypi/v/streamlit-analytics2)](https://pypi.org/project/streamlit-analytics2/)
[![Python](https://img.shields.io/pypi/pyversions/streamlit-analytics2)](https://pypi.org/project/streamlit-analytics2/)
[![Downloads](https://static.pepy.tech/badge/streamlit-analytics2/month)](https://pepy.tech/projects/streamlit-analytics2)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](https://github.com/444B/streamlit-analytics2/blob/main/LICENSE)
![Build](https://github.com/444B/streamlit-analytics2/actions/workflows/release.yml/badge.svg)

## Use it

1. Install:
   ```
   pip install streamlit-analytics2
   ```
2. Wrap your app:
   ```python
   import streamlit as st
   import streamlit_analytics2 as sa2

   with sa2.track():
       st.write("Hello")
       st.button("Click me")
   ```
3. Open your app with `?analytics=on` on the URL:
   ```
   http://localhost:8501/?analytics=on
   ```

That is the whole integration. Everything below is optional.

![Dashboard: views, visits, visitors, bounce rate, visit time, active now, views per page over time](https://raw.githubusercontent.com/444B/streamlit-analytics2/main/.github/images/dashboard.png)

## Keep the numbers across restarts

```python
with sa2.track(save_to_json="analytics.json"):   # counters + analytics.events.jsonl
    ...

with sa2.track(events_path="analytics.db"):      # SQLite, unlocks the query tab
    ...
```

## Protect the dashboard

```python
with sa2.track(unsafe_password=st.secrets["analytics_password"]):
    ...
```

The password is plain text inside the app, so keep it in `st.secrets` or an
environment variable and pick something you would not reuse.

## What the dashboard shows

- Views, visits, visitors, bounce rate, average visit time, active now.
- Views per page over time, hourly for today, with range and page filters.
- Pages, widgets, browsers, OS, devices, languages, regions, UTM sources and
  campaigns, custom events.
- A weekday-by-hour traffic-load heatmap and the busiest hour.
- Recent visits.
- **Raw data query**: read-only SQL over the SQLite log, example queries, CSV
  download and a chart picker. Needs `events_path` on a `.db` file and a
  password.

Your own runs with `?analytics=on` open are not counted.

![Breakdowns: pages, widgets, browsers, devices, OS, languages, regions](https://raw.githubusercontent.com/444B/streamlit-analytics2/main/.github/images/panels.png)

![Traffic load: weekday by hour heatmap](https://raw.githubusercontent.com/444B/streamlit-analytics2/main/.github/images/heatmap.png)

![Raw data query: SQL over your own event log, shown as a line chart](https://raw.githubusercontent.com/444B/streamlit-analytics2/main/.github/images/query.png)

## Track your own events

```python
if st.button("Generate report"):
    sa2.event("report generated", rows=len(df))
```

## Privacy

Stored per visit: a hash of address and browser that changes every day,
browser, OS and device family, language, timezone, theme, UTM tags, pages.
Stored per interaction: widget type, label, key, page and the chosen option.

Never stored: IP addresses, raw User-Agent strings, query strings, or anything
typed into text fields. Set `store_values=True` if you do want typed text.

## Options

| Argument | Default | What it does |
|---|---|---|
| `unsafe_password` | `None` | Password for the dashboard. Also gates the reset and the query tab. |
| `save_to_json` | `None` | Counters file (0.10 shape). Events go to `<name>.events.jsonl` beside it. |
| `load_from_json` | `None` | Load counters from that file at start. |
| `events_path` | `None` | Event log path. `.jsonl` by default, `.db` / `.sqlite` for SQLite. |
| `store` | `None` | Your own backend: any object with `append(events)` and `read()`. |
| `store_values` | `False` | Record typed text instead of `<text>`. |
| `session_id` | `None` | Also keep per-session counters in Firestore under this document. |
| `firestore_key_file`, `firestore_collection_name`, `firestore_document_name`, `firestore_project_name`, `streamlit_secrets_firestore_key` | | Persist the counters in Firestore. See the [wiki](https://github.com/444B/streamlit-analytics2/wiki). |
| `verbose` | `False` | Log what is loaded and saved. |

`start_tracking()` and `stop_tracking()` take the same arguments if you
prefer them to the `with` block. Every event is a plain record (`ts`, `kind`,
`session`, `visitor`, `page`, `name`, `widget_type`, `key`, `value`, `props`),
so the log is easy to feed into pandas, DuckDB or an LLM.

## Multipage apps

Call `sa2.track()` on every page. Views and widgets are recorded per page in
the event log and on the dashboard. The legacy counters in
`streamlit_analytics2.data` are shared across pages, as before.

## How it works

Streamlit already knows which widget a user changed on each rerun. This
library reads that from one place instead of wrapping every `st.*` function,
so widgets inside columns, forms, expanders, tabs, dialogs and the sidebar are
all seen, and a widget rendering with its default is never counted as a click.

## Upgrading from 0.10

Nothing to change in your code. The numbers will be lower because a widget
rendering with its default no longer counts as an interaction, typed text is
no longer stored unless you ask, and the dashboard reset now needs a
password. Details in
[CHANGELOG.md](https://github.com/444B/streamlit-analytics2/blob/main/CHANGELOG.md).

## Contributing

Issues and pull requests are welcome. See
[CONTRIBUTING.md](https://github.com/444B/streamlit-analytics2/blob/main/.github/CONTRIBUTING.md).
Development: `uv sync --all-extras && uv run pytest`. A dev app with every
widget type lives in `examples/dev/`; `examples/dev/seed.py` fills a dev log
with made-up traffic so the dashboard has something to show.

## License

MIT. See [LICENSE](https://github.com/444B/streamlit-analytics2/blob/main/LICENSE).
