mightys_pulse 0.9.2
mightys_pulse: ^0.9.2 copied to clipboard
Privacy-first analytics for Flutter apps and games on Android and iOS. Named events, no device IDs, offline queue. See your signals in the MightyS Pulse dashboard.
MightyS Pulse for Flutter #
Privacy-first analytics for Flutter apps and games. No device IDs, offline queue.
Docs: https://pulse.mightys.dev/docs/flutter/
Send named signals (events) with an optional number and a few properties, and see them in the MightyS Pulse dashboard. This package is for Flutter app and game developers who want usage numbers without advertising ids, device identifiers, cookies or fingerprinting.
Install #
flutter pub add mightys_pulse
Android release builds need network access, otherwise nothing is sent. Add <uses-permission android:name="android.permission.INTERNET" /> to android/app/src/main/AndroidManifest.xml, outside <application>. Flutter's template declares it only for debug and profile builds.
Quick start #
import 'package:flutter/widgets.dart';
import 'package:mightys_pulse/mightys_pulse.dart';
Future<void> main() async {
WidgetsFlutterBinding.ensureInitialized();
await Pulse.initialize('YOUR_APP_KEY'); // your app key from the Pulse dashboard
Pulse.track('level.complete');
Pulse.track('purchase', value: 4.99, props: {'sku': 'gems_100'});
runApp(const MyApp());
}
Users are counted without any setup. Other calls:
Pulse.setUser('internal-account-id'); // optional: use your own user id instead of the anonymous install id
Pulse.setUser(null); // back to the anonymous install id for later signals
await Pulse.flush(); // waits until queued signals are delivered
Public calls never throw into your app and never block the main thread. Calls made before initialize finishes are kept (up to 100) and sent afterwards. A second initialize is ignored.
What is sent and what is never sent #
Sent with every signal: your signal name, optional number and properties, a UTC timestamp, the debug flag, a random session id, platform (mobile or desktop), OS name and version, app version and build, device model, locale, and the SDK name and version. The app's package or bundle id is sent only if you set sendAppIdentity.
Sessions use a random 128-bit id that changes after 30 minutes of inactivity.
Anonymous install id: random, created by the SDK on first launch (16 random bytes from the platform's secure random generator) and stored only in the app's own storage, next to the offline queue. It is deleted with the app and replaced after opt-out. It is sent only as a SHA-256 hash, is not derived from any device identifier and is not shared between apps. Nothing needs to be set up for it.
User id: optional. If you call setUser, the hash of your id is sent instead of the install id hash. The id is hashed with SHA-256 on the device and the raw id is never stored or sent. The hash is pseudonymous and may still count as personal data. setUser(null) returns to the install id hash.
If the install id cannot be read or written, the SDK uses a random id kept in memory for that run.
Never sent: advertising ids, IDFV, Android ids, serial numbers, device names, host names, user names, location, contacts, cookies or signing certificate hashes.
Web: the package does nothing on Flutter web. It stores no install id, sets no cookies and sends no signals there.
IP address: the SDK does not read or send the device's IP address as data. As with any HTTP request, the server sees the connection address, uses it only to derive a two-letter country code and does not store it.
Do not put secrets or personal information in signal names or properties.
Options #
await Pulse.initialize('YOUR_APP_KEY', options: const PulseOptions(
flushIntervalSeconds: 30,
maxBatchSize: 100,
debug: false,
sendAppIdentity: false,
));
| Option | Default | Behaviour |
|---|---|---|
host |
https://in.mightys.dev |
Base URL (HTTP or HTTPS, no credentials, query or fragment). An invalid host or an empty key leaves the SDK inactive. |
flushIntervalSeconds |
20 | Seconds between batches after the first. Clamped to 0.05 through 3600. |
maxBatchSize |
100 | Signals per request. Clamped to 1 through 1000. |
maxQueueSize |
1000 | Signals kept offline. Clamped to 1 through 10000. The oldest are dropped first. |
maxQueueAgeDays |
7 | Days a queued signal is kept. Clamped to at most 29. |
gzip |
true | Compresses batches larger than 1024 bytes. |
debug |
true in debug builds, false in profile and release | Marks signals as test data and prints short diagnostics. See Test mode. |
sendAppIdentity |
false | Adds the package name as system.bundleId. |
appVersion |
from the platform | Overrides the app version. |
Test mode #
Every signal carries a debug flag. debug: true means test data, and the dashboard's test mode switch chooses whether you see test signals or real ones. You need only one app key per app: the same key serves both.
Unless you set it, PulseOptions.debug is true in a debug build (what flutter run starts) and false in profile and release builds. The default follows Flutter's build mode, is fixed for a given build and never changes while the app runs. An explicit value always wins, in both directions:
await Pulse.initialize('YOUR_APP_KEY', options: const PulseOptions(debug: true)); // force test data
Delivery and offline behaviour #
- The first batch after
initializeis sent at once. Later batches follow the interval, the batch size, an explicitflush, or the app moving to the background. - Signals are queued on disk and survive restarts. Network errors and server errors are retried with exponential backoff (one second up to five minutes), and a
Retry-Afterheader is honoured. - Encoding, compression and file work run off the main thread.
- Delivery is at least once: after a crash a batch can be sent again. If the OS ends the app abruptly, the last signals may be lost.
- A 401 response keeps the queue and stops sending until the app restarts.
- The queue lives in the app support directory and needs a single owning process. App extensions that share it are not supported.
Requirements #
- Android and iOS
- Dart 3.10 or newer, Flutter 3.38.1 or newer
Opt-out #
await Pulse.setOptOut(true) stops collection, clears the queue and cancels active requests; bytes already sent cannot be recalled. The choice is remembered across launches. Pulse.setOptOut(false) turns collection back on. Pulse.optOut reads the current state and is true until the stored choice has been read.
Licence #
MIT. See the LICENSE file.
Reference #
Signal names must be non-blank and at most 200 UTF-16 units, and values must be finite numbers. Properties may be String, bool (sent as "true" or "false"), int or finite double. Nested maps, lists, null and non-finite numbers are dropped. At most 32 properties are kept, in insertion order, with keys up to 128 and string values up to 1024 UTF-16 units, within 8192 UTF-8 bytes in total.
A runnable sample app is in the example folder:
cd example
flutter run --dart-define=PULSE_APP_KEY=YOUR_APP_KEY