tauri_plugin_better_posthog/

lib.rs

//! Tauri integration with PostHog.
//!
//! This plugin wraps the [`better_posthog`] crate to provide seamless analytics integration for Tauri applications.
//! It automatically handles:
//!
//! - User identity management with configurable strategies
//! - Session tracking across the application lifecycle
//! - Tauri-specific context injection (app name, version, webview info)
//! - Both Rust backend and frontend JavaScript event capture
//!
//! # Prerequisites
//!
//! The consuming application must initialize the `better_posthog` global client **before** registering the plugin:
//!
//! ```ignore
//! fn main() {
//!   // Initialize PostHog client first.
//!   let _guard = better_posthog::init(better_posthog::ClientOptions {
//!     api_key: Some("phc_your_api_key".into()),
//!     ..Default::default()
//!   });
//!
//!   tauri::Builder::default()
//!     .plugin(tauri_plugin_better_posthog::init())
//!     .run(tauri::generate_context!())
//!     .expect("error while running tauri application");
//! }
//! ```
//!
//! # Identity Strategies
//!
//! The plugin supports three identity strategies:
//!
//! - [`IdentityStrategy::Autogenerated`] (default): Persists a UUID v4 in the app data directory
//! - [`IdentityStrategy::Custom`]: Use a developer-provided closure to resolve the user ID
//! - [`IdentityStrategy::Anonymous`]: Each event gets a transient UUID v7
//!
//! # Example
//!
//! ```ignore
//! use tauri_plugin_better_posthog::{Builder, IdentityStrategy, PostHogExt, PostHogEvent};
//!
//! // Custom identity from your user system.
//! let plugin = Builder::new()
//!   .identity(IdentityStrategy::Custom(Box::new(|app_handle| {
//!     // Return user ID from your app's state.
//!     Some("user_123".to_string())
//!   })))
//!   .build();
//!
//! // Capture events from Rust
//! app.capture_event(MyCustomEvent { ... });
//! ```

mod commands;
mod identity;
mod state;

pub use identity::IdentityStrategy;
use tauri::plugin::{Builder as PluginBuilder, TauriPlugin};
use tauri::{Manager, Runtime};

/// Initializes the plugin with default settings.
#[must_use]
pub fn init<R: Runtime>() -> TauriPlugin<R> {
  Builder::default().build()
}

/// Builder for configuring the PostHog plugin.
pub struct Builder<R: Runtime> {
  identity_strategy: IdentityStrategy<R>,
}

impl<R: Runtime> Builder<R> {
  /// Creates a new plugin builder with default settings.
  #[must_use]
  pub fn new() -> Self {
    Self::default()
  }

  /// Sets the identity strategy for user identification.
  ///
  /// See [`IdentityStrategy`] for available options.
  #[must_use]
  pub fn identity(mut self, strategy: IdentityStrategy<R>) -> Self {
    self.identity_strategy = strategy;
    self
  }

  /// Builds the plugin with the configured settings.
  #[must_use]
  pub fn build(self) -> TauriPlugin<R> {
    PluginBuilder::new("better-posthog")
      .invoke_handler(tauri::generate_handler![commands::capture, commands::batch])
      .setup(move |app, _api| {
        let distinct_id = self.identity_strategy.resolve(app);

        let state = state::PluginState::new(distinct_id);
        app.manage(state);

        Ok(())
      })
      .build()
  }
}

impl<R: Runtime> Default for Builder<R> {
  fn default() -> Self {
    Self {
      identity_strategy: IdentityStrategy::default(),
    }
  }
}

/// Extension trait for capturing PostHog events.
///
/// This trait is automatically implemented for any type that implements [`Manager`](tauri::Manager).
pub trait PostHogExt<R: Runtime> {
  /// Captures an event defined via the [`PostHogEvent`] trait.
  fn capture_event(&self, event: impl PostHogEvent);

  /// Captures a batch of events efficiently.
  fn batch_events(&self, events: &[impl PostHogEvent]);
}

impl<R: Runtime, T: Manager<R>> PostHogExt<R> for T {
  fn capture_event(&self, event: impl PostHogEvent) {
    self.batch_events(&[event]);
  }

  fn batch_events(&self, events: &[impl PostHogEvent]) {
    let state = self.state::<state::PluginState>();
    let package_info = self.package_info();

    let distinct_id = state.distinct_id();
    let session_id = state.session_id();

    better_posthog::events::batch(
      events
        .iter()
        .map(|event| {
          let event_name = event.name();
          let properties = event.properties();

          #[allow(clippy::option_if_let_else)]
          let mut event = match distinct_id {
            Some(id) => better_posthog::Event::new(event_name, id),
            None => better_posthog::Event::new_anonymous(event_name),
          };

          for (key, value) in properties {
            event.insert_property(key, value);
          }

          event.insert_property("$session_id".to_string(), session_id);

          event.insert_property("$app".to_string(), package_info.name.clone());
          event.insert_property("$app_version".to_string(), package_info.version.to_string());

          #[cfg(target_os = "windows")]
          event.insert_property("$browser".to_string(), "webview2");
          #[cfg(not(target_os = "windows"))]
          event.insert_property("$browser".to_string(), "webkit");
          event.insert_property("$browser_version".to_string(), tauri::webview_version().ok());

          event
        })
        .collect(),
    );
  }
}

/// Trait for defining custom reusable PostHog events.
///
/// # Example
///
/// ```ignore
/// use std::collections::HashMap;
/// use tauri_plugin_better_posthog::PostHogEvent;
///
/// struct ButtonClick {
///   button_id: String,
///   page: String,
/// }
///
/// impl PostHogEvent for ButtonClick {
///   fn name(&self) -> &str {
///     "button_click"
///   }
///
///   fn properties(&self) -> HashMap<String, serde_json::Value> {
///     let mut properties = HashMap::new();
///     properties.insert("button_id".to_string(), self.button_id.clone().into());
///     properties.insert("page".to_string(), self.page.clone().into());
///     properties
///   }
/// }
/// ```
pub trait PostHogEvent {
  /// Returns the name of the event.
  fn name(&self) -> &str;

  /// Returns the custom properties associated with the event.
  fn properties(&self) -> std::collections::HashMap<String, serde_json::Value>;
}