Koma Analytics — Flutter SDK (koma_flutter)

Koma Analytics is a lightweight, developer-friendly analytics SDK for Flutter applications. It helps you track user events, identify users, and attach rich user properties with a clean API and minimal setup.

This SDK feels familiar if you've used tools like Amplitude or Mixpanel, while remaining simple and flexible. Events are queued durably and delivered reliably, even across app restarts and offline periods.

Features

  • 🚀 Simple event tracking
  • 👤 User identification
  • 🧩 User property management
  • 📦 Durable FIFO queue — no event loss on restart or disconnect
  • 🔁 Automatic retry with backoff; server-side deduplication
  • 📴 Offline-first, app-lifecycle aware
  • 🧭 Opt-in screen tracking via a navigator observer
  • 🟦 Type-safe, minimal public API

Get Started with Koma Analytics

Create a Koma Analytics account to start tracking events in your Flutter app.

👉 koma-analytics.ejaraapis.xyz

Once you've created a project, copy your API Key and API Secret and plug them into Koma.init.

Installation

dependencies:
  koma_flutter: ^1.0.0

flutter pub add koma_flutter

Quick Start

1. Initialize once, near app start

import 'package:flutter/widgets.dart';
import 'package:koma_flutter/koma_flutter.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();

  await Koma.init(const KomaConfig(
    apiKey: 'YOUR_API_KEY',
    apiSecret: 'YOUR_API_SECRET',
  ));

  runApp(const MyApp());
}

2. Track events anywhere

Koma.instance.track('button_clicked');

track, identify, and setUserProperty are synchronous and fire-and-forget — they enqueue durably and return immediately. Only Koma.init is asynchronous.

Koma.init(config)

Initializes the analytics client and opens the connection. Call it once, before runApp.

Option Type Required Description
apiKey String ✅ Your Koma API key
apiSecret String ✅ Your Koma API secret
debug bool — Print SDK logs (tagged [koma]) to the console. Off by default
onConnectionError callback — Called whenever the socket fails to connect, with a ConnectionError { message, code }

Example:

await Koma.init(KomaConfig(
  apiKey: apiKey,
  apiSecret: apiSecret,
  debug: kDebugMode,
  onConnectionError: (e) => debugPrint('${e.code.name}: ${e.message}'),
));

The API endpoint is managed internally by the SDK — production builds talk to the production API automatically. You do not configure a host.

Offline and retry behavior: events are persisted locally and flushed when the connection is available, so an app restart or a temporary disconnect never loses events. Each event carries a unique id that the backend deduplicates on, so retries never create duplicates.

Koma.instance

After init, use Koma.instance for all analytics calls. Accessing it before init throws a StateError.

track(eventName, [properties])

Tracks an event with optional properties.

void track(String eventName, [Map<String, dynamic>? properties]);

Example:

Koma.instance.track('page_viewed', {
  'page': 'Home',
  'referrer': 'Google',
});

Event names must be declared in your project's tracking plan — the backend rejects events (and properties) that aren't part of it.

identify([userId])

Identifies the current user by a unique ID.

void identify(String? userId);

Example:

Koma.instance.identify('user_123');

Passing null clears the identified user (a session reset).

setUserProperty(properties)

Sets or updates properties associated with the current user.

void setUserProperty(Map<String, dynamic> properties);

Example:

Koma.instance.setUserProperty({
  'plan': 'premium',
  'country': 'CM',
});

Screen Tracking (opt-in)

The SDK never emits an event you didn't ask for. To track screen views, either call track yourself, or install KomaNavigatorObserver with a mapper that returns an app-declared event (or null to skip a route):

MaterialApp(
  navigatorObservers: [
    KomaNavigatorObserver(
      mapper: (route) {
        final name = route.settings.name;
        if (name == null) return null;
        return KomaScreenEvent('Page Viewed', {'page_name': name});
      },
    ),
  ],
);

The mapper returns a KomaScreenEvent(eventName, properties) — the event name must exist in your tracking plan.

Error Handling

Analytics never throws into your app. Enrichment, storage, and network failures degrade gracefully. Socket connection failures are surfaced through onConnectionError:

onConnectionError: (e) {
  // e.code: unauthorized | forbidden | serverError | unknown
  // e.message: human-readable reason
}

Accessing Koma.instance before Koma.init throws:

StateError: Koma.init(...) must be called before Koma.instance.

Type Safety

The SDK is written in Dart with a small, fully-typed public surface: Koma, KomaConfig, ConnectionError / ConnectionErrorCode, and KomaNavigatorObserver / KomaScreenEvent.

Best Practices

  • Call Koma.init once at app start.
  • Call identify after login or signup; identify(null) on logout.
  • Use consistent event naming that matches your tracking plan.
  • Attach meaningful, plan-declared event properties.
  • Never send sensitive data (passwords, tokens, secrets) as properties.

Requirements

Dart ≥ 3.3 · Flutter ≥ 3.19 · Android minSdk 21 · iOS 15.

Libraries

koma_flutter
Koma Analytics SDK for Flutter.