mitr_flutter 0.2.0

Official Flutter SDK for Mitr Analytics — privacy-first, zero-PII event tracking for iOS, Android, desktop, and web.

mitr_flutter

Official Flutter SDK for Mitr Analytics — privacy-first, zero-PII event tracking for iOS, Android, desktop, and Flutter Web.

Install

flutter pub add mitr_flutter

Or add it to your pubspec.yaml directly:

dependencies:
  mitr_flutter: ^0.2.0

Get your Site ID and Secret Key

From the Mitr dashboard: Integration Hub → Add New App → Android / iOS / Desktop → paste your bundle/package ID. You'll get a Site ID and a Secret Key. Copy the secret key now — it's shown in full only once.

Unlike web apps (which authenticate by domain/Origin), mobile and desktop apps have no browser Origin for the backend to check, so the secret key is sent with every request instead. Keep it out of source control the same way you would any other API credential (environment-specific config, --dart-define, a secrets manager, etc.) — it doesn't need to be as tightly guarded as a database password since it only grants "write anonymized events for this one app", but it shouldn't be committed to a public repo either.

Initialize

Call this once, as early as possible (e.g. the top of main()):

import 'package:mitr_flutter/mitr_flutter.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();

  await MitrAnalytics.instance.initialize(
    siteId: 'YOUR_SITE_ID',
    secretKey: 'YOUR_SECRET_KEY',
  );

  runApp(const MyApp());
}

Automatic screen tracking

Add MitrNavigationObserver to your app's navigator observers and every named route push/pop/replace is tracked automatically — no per-screen code:

MaterialApp(
  navigatorObservers: [MitrNavigationObserver()],
  // ...
)

(Works the same with GoRouter's observers: parameter.)

Manual tracking

await MitrAnalytics.instance.pageView('/checkout');
await MitrAnalytics.instance.track('purchase_completed', meta: {
  'value': 49.99,
  'currency': 'USD',
});

Identifying users (login/logout)

// After a successful login:
MitrAnalytics.instance.identify(user.id);

// On logout:
MitrAnalytics.instance.reset();

Without identify(), events are attributed to a per-install anonymous id that's generated once and persisted (via shared_preferences) across app restarts. identify/track/pageView never send the raw id — it's SHA-256 hashed on-device, salted with your Site ID, before it's queued.

Options

await MitrAnalytics.instance.initialize(
  siteId: 'YOUR_SITE_ID',
  secretKey: 'YOUR_SECRET_KEY',
  baseUrl: 'https://api.mitranalytics.dev/api/v1', // default; override for self-hosted/staging
  enableLogging: true,                             // defaults to kDebugMode
  dryRun: false,                                   // true = log events instead of sending them
);

In debug builds, initialize() automatically fires a diagnostic ping to verify your Site ID/Secret Key are valid and reachable — check your console output (or the dashboard's "Verify Connection" step) if events aren't showing up.

Resilience

Events are batched (flushed every 10s or every 10 events) and persisted to disk between flushes, so an app killed mid-session doesn't lose queued events — they're sent on the next launch. Call MitrAnalytics.instance.flush() to force an immediate send, e.g. right before the app backgrounds.

Testing

flutter pub get
flutter test