Analytics

Setup

Analytics is off by default in every SDK (Flutter 12.9.0, JavaScript and React Native 12.4.0 and later). To turn it on, pass analyticsEnabled: true. Add KoolbaseNavigatorObserver to your MaterialApp for automatic screen tracking.

await Koolbase.initialize(KoolbaseConfig(
  publicKey: 'pk_live_xxx',
  baseUrl: 'https://api.koolbase.com',
  analyticsEnabled: true, // required: analytics is off by default
));

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

Tracking events

// 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.

// 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();

What is collected

Each event records its name and properties, the user properties you set, a random device ID created by the SDK, a session ID, the signed-in user's ID (if someone is signed in), the platform, your app version, the SDK version, and when it happened.

Once analytics is on, the SDK also records app_open, screen_view and session_end automatically. Events are stored in your project's analytics data in Koolbase, and deleted automatically after 30 days.

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.

// 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

API reference