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.