Databuckets Event Tracker SDK for Flutter

Lightweight analytics SDK for Flutter apps. Automatic event tracking, session management, and batched event delivery with SQLite storage and NDJSON format.

1. Setup

a. Add dependency

dependencies:
  databuckets_event_tracker: ^2.0.0

flutter pub get

b. Android configuration

No additional configuration needed. The SDK plugin registers automatically via Flutter's plugin system.

Minimum requirements: Android SDK 21+, compileSdk 33.

c. iOS configuration

No additional configuration needed. Add to your Podfile if not already present:

platform :ios, '11.0'

2. Initialize SDK

Call initialize() early in your app's lifecycle (e.g., in main() or initState()):

import 'package:databuckets_event_tracker/databuckets_event_tracker.dart';

final config = DatabucketsEventTrackerConfigBuilder(
  apiKey: 'your-api-key',
  baseUrl: 'https://your-endpoint.com',
)
  .setFlushThreshold(500)        // Flush when 500 events are queued
  .setMaxEventsStored(50000)     // Max events stored locally
  .setFlushInterval(10000)       // Flush every 10 seconds (ms)
  .setMaxFlushSizeKB(256)        // Max flush payload 256 KB
  .build();

await DatabucketsEventTracker.initialize(config);

Configuration parameters

Parameter	Description	Default
`flushThreshold`	Send events when queue reaches this count	500
`maxEventsStored`	Maximum events stored locally (SQLite + memory)	50,000
`flushInterval`	Periodic flush interval (ms)	10,000 (10s)
`maxFlushSizeKB`	Max HTTP payload size per batch (KB)	256

3. Record Events

Basic event

await DatabucketsEventTracker.record('button_click', {
  'button_id': 'purchase_btn',
  'screen': 'shop',
});

Event with timing

Calculate duration between two events:

// Record start event
await DatabucketsEventTracker.record('level_start');

// ... later, record end event with duration from start
await DatabucketsEventTracker.recordWithTiming(
  'level_complete',            // event name
  {'level': 5, 'score': 1200}, // params (optional)
  'duration_ms',               // timing property name
  'level_start',               // start event to measure from
);

Common properties

Properties attached to all subsequent events:

await DatabucketsEventTracker.setCommonProperties({
  'level': 1,
  'progress': 0.99,
});

// Or set a single property
await DatabucketsEventTracker.setCommonProperty('player_name', 'Alice');

Advanced: Event object

import 'package:databuckets_event_tracker/model/event.dart';

Event event = await Event.create('purchase');

event.setEventParams({'product_id': 'sku_5678', 'price': 49.99});
event.addEventParams({'currency': 'USD'});
event.addUserProperties({'membership': 'premium'});

await DatabucketsEventTracker.addEvent(event);

4. Exception Tracking

// Enable — captures uncaught Flutter and platform errors
DatabucketsEventTracker.enableExceptionLogTracking();

// Disable
DatabucketsEventTracker.disableExceptionLogTracking();

5. Stop & Resume

DatabucketsEventTracker.stop();    // Pause sending (events still stored locally)
DatabucketsEventTracker.resume();  // Resume sending

6. Flush

Force an immediate flush of queued events:

await DatabucketsEventTracker.flushNow();

7. Automatic Events

Event	Description
`first_open`	First app open after install. Always emitted once per install attempt and includes `first_open_install_diff_ms` plus `first_open_install_within_window` (`1` inside the install window, `0` outside). Delivery-confirmed via HTTP 200.
`session_start`	New session started (30-minute inactivity timeout).
`app_focus_end`	App moved to background. Includes `app_focus_duration` in milliseconds.
`app_exception_log`	Uncaught exception (when exception tracking is enabled).

Session management

Sessions auto-start on first event or after 30 minutes of inactivity.
session_id format: {user_pseudo_id}:{session_start_timestamp}
session_number increments per new session.
session_progress = seconds elapsed since session start.

8. Default Event Properties

Every event automatically includes:

Property	Type	Example
`event_date`	int	`20250505`
`event_local_day_of_week`	String	`"1 - Monday"`
`event_local_hour`	int	`11`
`event_local_hour_minute`	int	`1106`
`install_day`	int	`20250415` or `-1`
`retention_day`	int	`20` or `-1`
`retention_hour`	int	`480` or `-1`
`retention_minute`	int	`28800` or `-1`
`session_id`	String	`"db-xxxx:1746417808764"`
`session_progress`	int	`170`
`session_number`	int	`5`
`user_pseudo_id`	String	`"db-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"`
`sdk_ver`	String	`"2.0.0"`
`sdk_ver_num`	int	`200`
`engagement_time_msec`	int	`3500`

install_day is best-effort. If the native install-time lookup times out, fails, or returns an invalid value and the SDK has no valid cached install timestamp yet, the emitted event uses install_day = -1. In that same state, retention_day, retention_hour, and retention_minute are also emitted as -1.

User properties (auto-collected)

Property	Type	Example
`geo`	Map<String, dynamic>	`{"country":"VN"}`
`app_platform`	String	`"android"`
`app_store`	String?	`null` on Android, `"App Store"` on iOS
`app_version`	String	`"1.0.0"`
`app_id`	String	`"com.example.myapp"`
`device`	Map<String, dynamic>	`{"brand_name":"google","model":"Pixel 7","platform_version":"14","user_default_language":"en-US","timezone_offset_seconds":25200,"category":"mobile","id":"7a349ab563648412","is_limited_ad_tracking_enabled":false,"resettable_id":"6b6d4c6f-..."}`
`ip_country_code`	String	`"VN"`
`appid`	String	`"com.example.myapp"`
`platform`	String	`"android"`

Serialized NDJSON payloads keep geo and device as nested top-level objects. The runtime does not emit dotted keys such as geo.country or device.brand_name.

9. Pre-init Event Buffering

Events recorded before initialize() completes are buffered (up to 200 normal events, 1000 for critical events like first_open, session_start, ad_impression). They are automatically drained after initialization.

10. Storage

Primary: SQLite with WAL mode (up to maxEventsStored events).
Fallback: In-memory queue (500 events) if SQLite is unavailable.
Format: NDJSON (newline-delimited JSON) with Content-Type: application/x-ndjson.
SQLite-backed events persist across app restarts until successfully sent (HTTP 200).
If SQLite is unavailable and the SDK is using the in-memory fallback queue, those fallback events are not restart-durable and can be lost on app restart.

11. Notes

user_pseudo_id is auto-generated as "db-" + UUID v4 on first launch and persisted.
No Firebase dependency required.
SDK does not block the main thread — all I/O is async.
Geo info (IP country code) is fetched asynchronously and does not block event sending.