# Tauri Plugin for Telemetry
> Backend-agnostic analytics/telemetry plugin for desktop and mobile apps built with Tauri v2. Send events to any backend that implements the ingest protocol.
Rust Crate: `tauri-plugin-telemetry`
Install (Rust): `cargo add tauri-plugin-telemetry`
npm Package: `tauri-plugin-telemetry`
Install (JS): `npm add tauri-plugin-telemetry`
Repo: https://github.com/lispking/tauri-plugin-telemetry
## Overview
This plugin instruments Tauri v2 apps with events and sends them to a
user-configurable analytics backend. It is not tied to any specific vendor —
point it at your own backend via `InitOptions.host`.
- Set `InitOptions.host` to point the plugin at your analytics backend; the App Key can be any string
- Only strings and numbers are allowed as custom property values
- All tracking is non-blocking and runs in the background
- No events are tracked automatically — you must call `track_event`/`trackEvent` manually
- The plugin automatically captures OS, app version, locale, and other system properties
## Important: Dual API (Rust + JavaScript)
This plugin provides **two APIs** — use whichever fits your app architecture:
- **Rust API** — use `EventTracker` trait on `App`, `AppHandle`, or `Window`
- **JavaScript API** — use `trackEvent()` from `tauri-plugin-telemetry` in your webview frontend
Both APIs require the Rust plugin to be registered in your Tauri builder. The JS API calls the Rust backend via Tauri's IPC.
## Installation
### 1. Add the Rust crate
In `src-tauri/Cargo.toml`:
```toml
[dependencies]
tauri-plugin-telemetry = "0.1.1"
```
### 2. Add the JS package (optional, for webview tracking)
```bash
npm add tauri-plugin-telemetry
```
### 3. Register the plugin
In `src-tauri/src/main.rs` (or `lib.rs`):
```rust
fn main() {
tauri::Builder::default()
.plugin(tauri_plugin_telemetry::init("APP_KEY"))
.run(tauri::generate_context!())
.expect("error while running tauri application");
}
```
If you need to point the plugin at your own backend, use `Builder::with_host`:
```rust
fn main() {
tauri::Builder::default()
.plugin(tauri_plugin_telemetry::Builder::new("APP_KEY")
.with_host("https://analytics.myapp.com")
.build())
.run(tauri::generate_context!())
.expect("error while running tauri application");
}
```
For full control over all options, use `with_options`:
```rust
use tauri_plugin_telemetry::{Builder, InitOptions};
use std::time::Duration;
fn main() {
let opts = InitOptions {
host: Some("https://analytics.myapp.com".into()),
flush_interval: Some(Duration::from_secs(30)),
api_path: Some("/ingest".into()),
..Default::default()
};
tauri::Builder::default()
.plugin(Builder::new("APP_KEY").with_options(opts).build())
.run(tauri::generate_context!())
.expect("error while running tauri application");
}
```
### 4. Add ACL permission
Add `telemetry:allow-track-event` to your Tauri capabilities to allow the JS API to send events. In your `src-tauri/capabilities/*.json`:
```json
{
"permissions": ["telemetry:allow-track-event"]
}
```
## Track Events (Rust)
Import the `EventTracker` trait and call `track_event` on `App`, `AppHandle`, or `Window`:
```rust
use tauri_plugin_telemetry::EventTracker;
// Event with no properties
app.track_event("app_started", None);
// Event with properties (serde_json::Value)
app.track_event("screen_view", Some(serde_json::json!({ "name": "Settings" })));
```
Full example with startup and exit events:
```rust
use tauri_plugin_telemetry::{init, EventTracker};
fn main() {
tauri::Builder::default()
.plugin(init("APP_KEY"))
.setup(|app| {
app.track_event("app_started", None);
Ok(())
})
.build(tauri::generate_context!())
.expect("error while running tauri application")
.run(|handler, event| match event {
tauri::RunEvent::Exit { .. } => {
handler.track_event("app_exited", None);
handler.flush_events_blocking();
}
_ => {}
});
}
```
## Track Events (JavaScript)
```js
import { trackEvent } from "tauri-plugin-telemetry";
trackEvent("app_started");
```
## Track Events with Properties (JavaScript)
```js
import { trackEvent } from "tauri-plugin-telemetry";
trackEvent("screen_view", { name: "Settings" });
trackEvent("purchase", { plan: "pro", price: 9.99 });
```
## Configuration
For most cases, `with_host` is enough:
```rust
tauri_plugin_telemetry::Builder::new("APP_KEY")
.with_host("https://analytics.myapp.com")
.build()
```
All available options (with their defaults):
```rust
use tauri_plugin_telemetry::{Builder, InitOptions};
use std::time::Duration;
Builder::new("APP_KEY")
.with_options(InitOptions {
host: Some("https://analytics.myapp.com".into()), // required
flush_interval: Some(Duration::from_secs(30)), // default 60s release / 2s debug
api_path: Some("/v1/events".into()), // default /v1/events
app_key_header: Some("App-Key".into()), // default App-Key
sdk_name: Some("myapp@1.0.0".into()), // default <crate>@<version>
..Default::default()
})
.build()
```
- `host` — base URL of the backend. **Required** to enable tracking; the
plugin sends events to `{host}{api_path}`. There is no implicit host
resolution — the plugin is backend-agnostic.
- `api_path` — path appended to `host` to form the ingest URL. Default `/v1/events`.
- `app_key_header` — name of the HTTP header carrying the App Key. Default `App-Key`.
- `sdk_name` — value reported as `systemProps.sdkVersion`. Default `<crate-name>@<crate-version>`.
- `flush_interval` — defaults to 60s in release, 2s in debug mode.
- Events are batched (25/batch) and flushed periodically; `flush_events_blocking()` forces an immediate flush.
### Using a custom backend
The plugin is backend-agnostic: point it at any backend that implements its
ingest protocol by setting `host` (and `api_path` / `app_key_header` if your
backend deviates from the defaults).
## Platform Notes
- Requires Tauri v2 (2.x)
- Rust edition 2024
- The `EventTracker` trait is implemented for `App`, `AppHandle`, and `Window`
- The JS `trackEvent` is async but you don't need to await it
- A custom panic hook can be set via `Builder::with_panic_hook()` to track crashes