New in v2.3.0

Analytics

Track screen views, custom events, and user behaviour in your Flutter app. View DAU, WAU, MAU, top events, and top screens in the Koolbase dashboard.

Setup

Analytics is enabled by default. Add KoolbaseNavigatorObserver to your MaterialApp for automatic screen tracking.

dart

await Koolbase.initialize(KoolbaseConfig(
  publicKey: 'pk_live_xxx',
  baseUrl: 'https://api.koolbase.com',
  analyticsEnabled: true, // default — can be omitted
));

// Add to MaterialApp for automatic screen tracking
MaterialApp(
  navigatorObservers: [
    KoolbaseNavigatorObserver(client: Koolbase.analytics),
  ],
  home: const HomeScreen(),
)

Auto events

On initialize, Koolbase automatically tracks app_open. KoolbaseNavigatorObserver tracks screen_view on every navigation push, pop, and replace. session_end fires when the analytics client is disposed.

Tracking events

dart

// Custom event
Koolbase.analytics.track('purchase', properties: {
  'value': 1200,
  'currency': 'GHS',
  'product_id': 'prod_123',
});

// Screen view (manual — use this if not using NavigatorObserver)
Koolbase.analytics.screenView('checkout');

// Screen view with extra properties
Koolbase.analytics.screenView('product_detail', properties: {
  'product_id': 'prod_123',
  'category': 'electronics',
});

User identity

By default events are tracked anonymously using a stable device ID. When a user logs in, attach their ID so events are linked to a known user.

dart

// After login — attach user ID to all subsequent events
final session = await Koolbase.auth.login(email, password);
Koolbase.analytics.identify(session.user.id);

// Set user properties for segmentation
Koolbase.analytics.setUserProperty('plan', 'pro');
Koolbase.analytics.setUserProperty('country', 'GH');

// Set multiple at once
Koolbase.analytics.setUserProperties({
  'plan': 'pro',
  'country': 'GH',
  'signup_date': '2026-01-15',
});

// On logout — clear identity
await Koolbase.auth.logout();
Koolbase.analytics.reset();

Batching and flush

Events are queued locally and flushed in batches to reduce network overhead. The SDK flushes automatically — you rarely need to call flush manually.

Flush triggers

Events are flushed automatically: every 30 seconds, when the queue reaches 20 events, when the app goes to background, and when the analytics client is disposed. On network failure, events are re-queued and retried on the next flush.

dart

// Manual flush — e.g. before a critical action
await Koolbase.analytics.flush();

// Dispose on app close (call from your app lifecycle handler)
await Koolbase.analytics.dispose();

Dashboard

View your analytics data in the Koolbase dashboard under Analytics in your project sidebar. The dashboard shows:

DAU, WAU, MAU — active user counts
Total events, unique devices, unique users
Events over time — line chart with 7d / 14d / 30d range
Top events — ranked by count with usage bar
Top screens — ranked by view count
Funnels — define event sequences, visualize drop-off per step
Retention — weekly cohort heatmap, color-coded by return rate

Data retention

Raw events are stored for 30 days. Events older than 30 days are purged nightly. Dashboard aggregates reflect the selected date range (7d, 14d, or 30d).

API reference

Method	Description
`Koolbase.analytics.track(event, properties)`	Track a custom event with optional properties.
`Koolbase.analytics.screenView(name, properties)`	Track a screen view manually.
`Koolbase.analytics.identify(userId)`	Attach an authenticated user ID to events.
`Koolbase.analytics.setUserProperty(key, value)`	Set a single user property.
`Koolbase.analytics.setUserProperties(map)`	Set multiple user properties at once.
`Koolbase.analytics.reset()`	Clear user identity and properties on logout.
`Koolbase.analytics.flush()`	Manually flush the event queue.
`Koolbase.analytics.dispose()`	Flush and shut down — call on app close.
`KoolbaseNavigatorObserver`	Add to MaterialApp.navigatorObservers for auto screen tracking.

Logic Engine

Cloud Messaging