openpanel #

OpenPanel analytics for Flutter with native Android (Kotlin) and iOS (Swift) clients, a persistent offline event queue and batching.

OpenPanel does not ship an official Flutter SDK — this package fills the gap with hand-written native clients that speak the documented /track REST API directly, mirroring the API of the official mobile SDKs.

Features #

• Native clients, zero native dependencies: Kotlin (HttpURLConnection) and Swift (URLSession) implementations, no OpenPanel SDK dependencies, no third-party libraries.
• Full API: track, identify, increment, decrement, setGlobalProperties, clear, flush — everything the official mobile SDKs expose.
• Persistent offline queue: events survive app restarts (capped at 500, oldest dropped first).
• Batching: the queue is flushed when it reaches 10 events, 5 seconds after the first queued event, when the app goes to the background, or on an explicit flush(). Failures retry with exponential backoff (0.5s up to 60s); events rejected with a 4xx are dropped instead of blocking the queue.
• Lifecycle tracking: automatic app_opened / app_closed events (opt-out via automaticTracking: false).
• Device metadata on every event: OS name/version, device model/manufacturer, screen size, app version/build, locale, SDK version.
• Self-hosted support via apiUrl.
• Analytics never crashes the app: platform errors are swallowed (logged in debug), release builds drop events sent before initialization.

Platform support #

Android release builds need the INTERNET permission in the main manifest (the Flutter debug template adds it only for debug builds). Networked apps already have it.

Usage #

Initialize #

import 'package:openpanel/openpanel.dart';

await Openpanel.instance.initialize(
  OpenpanelOptions(clientId: 'YOUR_CLIENT_ID'),
);

For a self-hosted instance:

await Openpanel.instance.initialize(
  OpenpanelOptions(
    clientId: 'YOUR_CLIENT_ID',
    apiUrl: 'https://openpanel.example.com',
  ),
);

Events tracked before initialization completes are held back and delivered afterwards. In debug builds tracking before initialize throws a StateError to surface mis-wiring early; in release builds such events are dropped silently.

Track events #

Openpanel.instance.track('button_clicked', properties: {
  'button': 'signup',
});

Property values must be JSON-compatible primitives (num, String, bool, null, lists and nested maps of those).

Identify users #

Openpanel.instance.identify(
  'user-42',
  firstName: 'John',
  email: 'john@example.com',
  properties: {'plan': 'pro'},
);

After identify, every subsequent track event carries the profileId. The binding persists across app restarts until clear() is called.

Profile counters #

Openpanel.instance.increment('user-42', 'login_count', value: 1);
Openpanel.instance.decrement('user-42', 'credits_remaining', value: 5);

Global properties #

Openpanel.instance.setGlobalProperties({'environment': 'production'});

Merged into every future track event (event properties win on conflicts); persists across app restarts until clear().

Screen views (optional) #

MaterialApp(
  navigatorObservers: [OpenpanelNavigatorObserver()],
  // ...
);

Reports screen_view events with { 'name': <route name> } for routes that have a non-empty name.

API #

Options #

Example #

See the example app. Run it with your credentials:

cd example && flutter run \
  --dart-define=OPENPANEL_CLIENT_ID=... \
  --dart-define=OPENPANEL_API_URL=https://your-openpanel.example.com

Comparison with openpanel_flutter #

The existing community package is an unofficial thin client. Differences:

• identify / increment / decrement (profile attributes and counters) — this package supports them.
• Persistent offline queue — events survive restarts; both official SDKs and the community package keep at most an in-memory buffer.
• Actively built on the documented REST protocol ({type, payload} envelopes) instead of the unpublished Kotlin SDK.

License #

MIT — see LICENSE.