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
  • User identification with custom attributes (setUser)
  • 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.

User Identification

Call setUser to associate events with a known user. The userId is your own application's user identifier — the SDK does not generate or validate it. Call it once the user is known (typically at session start, e.g. after login) and again whenever the user's details change.

B2Metric.instance.setUser(B2MetricUser(
  userId: 'user_123',
  name: 'Ahmet',
  email: 'ahmet@example.com',
  properties: {'plan': 'premium'}, // any custom attributes
));

userId is required; name, surname, and email are suggested fields. Custom attributes are passed via properties.

setUser does two things:

  1. Sends a user_identify event that creates or updates the user's profile attributes.
  2. Merges the attributes into the user_properties of every subsequent event, so they are available for event-level analysis.

Device fields cannot be overridden. If a custom attribute uses the same key as a collected device property (e.g. device_id, os_version), the device value always wins.

The user_properties attached to each event is a snapshot taken at the moment the event is tracked. Calling setUser later does not change already-queued events. User attributes are not persisted across restarts, so call setUser again after each app launch.

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