tauri-plugin-telemetry 0.1.0

# Tauri Plugin for Telemetry

A backend-agnostic analytics/telemetry plugin for Tauri v2 apps. Send events to
**any** backend that implements the ingest protocol — point the plugin at your
own backend with `InitOptions.host`.

## Install

Add the Rust crate to `src-tauri/Cargo.toml`:

```toml
[dependencies]
tauri-plugin-telemetry = "0.1.0"
```

```toml
[dependencies]
tauri-plugin-telemetry = { git = "https://github.com/lispking/tauri-plugin-telemetry" }
```

Install the JavaScript guest bindings with your preferred package manager:

```bash
npm add @telemetry/tauri
```

```bash
npm add https://github.com/lispking/tauri-plugin-telemetry
```

## Usage

Register the plugin with Tauri, pointing it at your analytics backend via
`InitOptions.host`:

`src-tauri/src/main.rs`

```rust
use tauri_plugin_telemetry::{Builder, InitOptions};

#[tokio::main]
async fn main() {
    let opts = InitOptions {
        host: Some("https://analytics.myapp.com".into()), // your backend
        ..Default::default()
    };

    tauri::Builder::default()
        .plugin(Builder::new("my-app-key-123").with_options(opts).build())
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}
```

Then add `telemetry:allow-track-event` to your Access Control List.

Send events from Rust via the `EventTracker` trait:

```rust
use tauri_plugin_telemetry::EventTracker;

#[tokio::main]
async fn main() {
    tauri::Builder::default()
        .plugin(/* ...as above... */)
        .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();
            }
            _ => {}
        })
}
```

The `trackEvent` function is also available through the JavaScript guest bindings:

```js
import { trackEvent } from "@telemetry/tauri";

trackEvent("save_settings") // An event with no properties
trackEvent("screen_view", { name: "Settings" }) // An event with a custom property
```

A few important notes:

1. The plugin automatically enriches each event with useful information: OS,
   app version, locale, and other system properties.
2. You're in control of what gets sent. No events are tracked automatically —
   call `trackEvent` manually (it's recommended to at least track one event at
   startup).
3. You don't need to await `trackEvent`; it runs in the background.
4. Only string and number values are allowed in custom properties.

## Providing the APP_KEY via .env

You can load the App Key from a `.env` file at compile time using the
`dotenvy_macro` crate. The `.env` file must be in the `src-tauri` directory.

```rust
use tauri_plugin_telemetry::{Builder, EventTracker, InitOptions};
use dotenvy_macro::dotenv;

#[cfg_attr(mobile, tauri::mobile_entry_point)]
pub fn run() {
    let opts = InitOptions {
        host: Some("https://analytics.myapp.com".into()),
        ..Default::default()
    };

    tauri::Builder::default()
        .build(tauri::generate_context!())
        .plugin(Builder::new(dotenv!("APP_KEY")).with_options(opts).build())
        .expect("Error when building tauri app")
        .run(|handler, event| match event {
            tauri::RunEvent::Exit { .. } => {
                handler.track_event("app_exited", None);
                handler.flush_events_blocking();
            }
            tauri::RunEvent::Ready { .. } => {
                handler.track_event("app_started", None);
            }
            _ => {}
        });
}
```

For AI/LLM integration instructions, see [llms.txt](./llms.txt)

## Using a custom backend (self-hosting)

The plugin can point at any backend that implements its ingest protocol. The
relevant `InitOptions` fields:

```rust
use tauri_plugin_telemetry::{Builder, InitOptions};

let opts = InitOptions {
    // Your analytics backend base URL. Required to enable tracking.
    host: Some("https://analytics.myapp.com".into()),
    // All of the following are optional and default to the values shown.
    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()
};

tauri::Builder::default()
    .plugin(Builder::new("my-app-key-123").with_options(opts).build())
    .run(tauri::generate_context!())
    .expect("error while running tauri application");
```

Inspired by the [Aptabase](https://aptabase.com/) analytics platform, which is a great option if you don't want to self-host.