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

While the platform is self-hosted, add it via git or a path dependency:

# pubspec.yaml
dependencies:
  baseerh_sdk:
    git:
      url: https://github.com/baseerh/platform.git
      path: packages/sdk-flutter

Once published to pub.dev (see Publishing):

dependencies:
  baseerh_sdk: ^0.1.0

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