b2metric_sdk

B2Metric analytics SDK for Flutter. Collects events, manages sessions, and supports push notifications on both Android and iOS.

Features

  • Custom event tracking with properties and item-level data
  • Automatic session management (first_open, session_start, session_end)
  • Push notification token registration (FCM, HMS, APNS) and open tracking
  • Offline event queuing with persistent storage
  • Automatic batching, retry with exponential backoff, and network-aware delivery
  • Automatic device and app metadata collection
  • Configurable log levels for debugging
  • Zero third-party dependencies (uses Flutter SDK only)

Requirements

  • Flutter >= 3.10
  • iOS 13+ / Android API 24+

Installation

dependencies:
  b2metric_sdk: ^0.1.0

Quick Start

import 'package:b2metric_sdk/b2metric_sdk.dart';

// Initialize at app startup
await B2Metric.instance.init(
  const B2MetricConfig(
    apiKey: 'YOUR_API_KEY',
    appIdentifier: 'YOUR_APP_IDENTIFIER',
  ),
);

// Track an event
B2Metric.instance.logEvent('button_click', properties: {
  'screen': 'home',
});

Initialization

Call init() once at app startup before using any other SDK method. Subsequent calls are ignored.

await B2Metric.instance.init(
  const B2MetricConfig(
    apiKey: 'YOUR_API_KEY',
    appIdentifier: 'YOUR_APP_IDENTIFIER',
    logLevel: LogLevel.debug,
  ),
);

Configuration Options

Option Type Required Default Range Description
apiKey String Yes — — Your B2Metric API key
appIdentifier String Yes — — Identifier of your app registered in B2Metric (see format rules below)
baseUrl String No "https://tracker.b2metric.com" — API endpoint URL
batchSize int No 20 1–100 Events per batch before sending
flushIntervalSeconds int No 30 1–3600 Seconds between automatic flushes
maxRetries int No 3 1–10 Retry attempts for failed requests
sessionTimeoutMinutes int No 30 1–10080 Inactivity before a new session starts
maxQueueSize int No 1000 100–10000 Max events held in queue
logLevel LogLevel No LogLevel.off off · error · warning · info · debug Console log verbosity

Values outside the allowed range are clamped automatically.

appIdentifier format

appIdentifier must be lowercase snake_case:

  • Allowed characters: a–z, 0–9 and _
  • Must start with a letter
  • Cannot contain spaces, hyphens, uppercase letters, Turkish or other non-ASCII characters, or consecutive __
  • Cannot start or end with _
✅ Valid ❌ Invalid
my_app MyApp (uppercase)
my_app_v2 my-app (hyphen)
checkout_web my app (space)
app123 şirket (Turkish character)
a_b_c 123app (leading digit)
_myapp / myapp_ (leading/trailing _)
my__app (consecutive _)

Event Tracking

Basic Event

B2Metric.instance.logEvent('page_view', properties: {'page': 'home'});

Event with Item Properties

B2Metric.instance.logEvent(
  'add_to_cart',
  properties: {'total': 3000, 'currency': 'USD'},
  itemProperties: [
    {'id': 'SKU-123', 'name': 'Running Shoes', 'price': 2850, 'quantity': 1},
    {'id': 'SKU-456', 'name': 'Socks', 'price': 150, 'quantity': 2},
  ],
);

Supported Property Types

String, num, bool, DateTime, null, Map<String, dynamic>, and List<dynamic>. Unsupported values are dropped with a warning.

Push Notifications

Register Token

B2Metric.instance.registerPushToken(token, PushProvider.fcm);

Supported providers: PushProvider.fcm, PushProvider.hms, PushProvider.apns.

Track Push Opened

B2Metric.instance.trackPushOpened({
  'campaign_id': 'summer_sale',
  'deep_link': 'app://offers/42',
});

Manual Flush

B2Metric.instance.logEvent('purchase_completed', properties: {'order_id': 'ord_789'});
await B2Metric.instance.flush();

Shutdown

await B2Metric.instance.destroy();

License

MIT

Libraries

b2metric_sdk