Baseera Flutter SDK (baseerh_sdk)

Product analytics + customer engagement for Flutter apps, with native Arabic/RTL-friendly data and PDPL-compliant consent built in. Pure Dart — no platform-channel glue — targeting iOS & Android (Flutter ≥ 3.10).

It speaks the same wire protocol as the Web, React Native, iOS, and Android SDKs, so events land in the same dashboard alongside every other client.

Install

flutter pub add baseerh_sdk

or add it directly:

# pubspec.yaml
dependencies:
  baseerh_sdk: ^0.1.0

Published on pub.dev/packages/baseerh_sdk.

Quick start

import 'package:baseerh_sdk/baseerh_sdk.dart';

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

  await Baseerh.instance.setup(
    const BaseerhConfig(
      apiKey: 'pk_live_xxx',        // from dashboard → Settings → API Keys
      // host defaults to https://api.baseerh.com (the gateway)
    ),
  );

  runApp(const MyApp());
}

// Anywhere in your app:
Baseerh.instance.capture('product_viewed', properties: {'sku': 'A-100'});
Baseerh.instance.identify('user-42', properties: {'plan': 'pro'});

Always point at the gateway host (api.baseerh.com), never the control plane.

Configuration

Option	Default	Notes
apiKey	—	Required. Platform key (pk_*).
host	https://api.baseerh.com	Gateway URL.
tenantId	null	Usually inferred server-side; set for test harnesses.
flushInterval	30s	Auto-flush cadence.
flushAt	20	Flush when the queue hits this size.
maxRetries	3	Exponential backoff before parking a batch.
maxQueueSize	1000	Drop-oldest overflow cap.
captureLifecycle	true	Auto-track app open/background.
defaultOptIn	true	Set false for opt-in-required PDPL flows.
debug	false	Verbose logging.
bootstrapFeatureFlags	null	Flags to use before the first /v1/decide.

API surface

Core — setup, capture, identify, alias, group, screen, trackRevenue, setPersonProperties, reset, flush.

Feature flags — isFeatureEnabled, getFeatureFlag, getFeatureFlagPayload, reloadFeatureFlags, onFeatureFlags.

Consent (PDPL) — optIn, optOut, hasOptedIn, hasOptedOut, getConsentState. Capture is blocked while opted out.

Push — registerDeviceToken(token, PushProvider.fcm), trackPushOpened, trackPushReceived. The token itself comes from your app's firebase_messaging / APNs setup; the SDK only forwards it.

Deep links — trackDeepLink(url). Flutter has no global URL listener, so call this from your router or app_links/uni_links handler.

Engagement — getContentCards, trackCardImpression/Click/dismissCard, getSurveys, submitSurveyResponse, getPreferences, updatePreference.

Diagnostics — onError, debug, destroy.

Push example

// Using firebase_messaging:
final token = await FirebaseMessaging.instance.getToken();
if (token != null) {
  await Baseerh.instance.registerDeviceToken(token, PushProvider.fcm);
}

How it works

Events are buffered in a persistent queue (shared_preferences), batched to POST /v1/batch, and survive app restarts. Feature flags come from POST /v1/decide and are cached on disk. The queue retries with exponential backoff, honours HTTP 429 Retry-After, drops the oldest events on overflow, truncates oversized payloads (32KB/event, 1KB/property), and pauses while offline — resuming automatically on reconnect.

Publishing

Dart/Flutter packages are not published to npm. The registry is pub.dev:

flutter pub publish --dry-run   # validate
flutter pub publish             # publish (requires a pub.dev account)

Options, in order of how this repo's other SDKs are distributed:

1. Git / path dependency (recommended while self-hosted) — consumers point pubspec.yaml at this repo path. No registry account needed; mirrors how the iOS (SwiftPM/git) and Android (local) SDKs are consumed today.
2. Public pub.dev — for a public package. Requires a verified publisher (e.g. baseerh.com) and bumping version here + in CHANGELOG.md.
3. Private pub repository — host an internal pub server and set publish_to: in pubspec.yaml.

Bump version in pubspec.yaml, lib/src/version.dart, and CHANGELOG.md together on every release.

Development

flutter pub get
flutter test       # 18 unit tests
flutter analyze
cd example && flutter run