Skip to Content
DevelopersSDKsFlutter SDKQuickstart

Flutter SDK

The Active Reach Flutter SDK provides a Dart API with platform channel bridges to native iOS and Android SDKs.

Current version: [email protected] (Phase 5.5 readiness pass — pub.dev verified-publisher status pins the 1.0.0 graduation).

Brand canon. The pub.dev package is active_reach_sdk, but the Dart class you call is still Aegis (and the config type is still AegisConfig). The package re-exports the internal aegis_flutter.dart subtree under the canonical active_reach_sdk.dart entry point — “Aegis” is the internal source-tree name; “Active Reach” is the customer-facing identifier on pub.dev.

Installation

Add to your pubspec.yaml:

dependencies:
  active_reach_sdk: ^0.7.0

Then run:

flutter pub get

Initialization

Initialize in your app’s main():

import 'package:active_reach_sdk/active_reach_sdk.dart';
 
void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Aegis.init(
    writeKey: 'YOUR_WRITE_KEY',
    config: AegisConfig(workspaceId: 'YOUR_WORKSPACE_ID'),
  );
  runApp(const MyApp());
}

Core tracking

// Track a custom event
Aegis.track('order_completed', properties: {
  'order_id': 'ORD-123',
  'amount': 4999,
  'currency': 'INR',
});
 
// Identify a user
Aegis.identify('user_456', traits: {
  'name': 'Priya Sharma',
  'email': '[email protected]',
  'plan': 'pro',
});
 
// Track a screen view
Aegis.screen('Product Detail', properties: {'product_id': 'SKU-A'});
 
// Group, reset, flush
Aegis.group('company_789', traits: {'name': 'Acme Corp'});
Aegis.reset();
Aegis.flush();

The Flutter SDK mirrors the same method signatures as the Web and React Native SDKs. Native push and in-app bridges work via platform channels — no additional Dart configuration needed beyond initialization.

E-commerce + governance + cell selection (Phase 1, SDK ≥0.2.0)

import 'package:active_reach_sdk/active_reach_sdk.dart';
import 'package:active_reach_sdk/active_reach_sdk.dart';
 
await AegisFlutter.initialize(
  'YOUR_WRITE_KEY',
  cellEndpoints: const [
    CellEndpoint(region: CellRegion.apSouth, url: 'https://ap-south.api.aegis.ai'),
  ],
  preferredRegion: CellRegion.apSouth,
  workspaceId: 'ws_abc123',
);
 
// Bootstrap auto-arms NameGovernor with the returned EventGovernanceHint.
final result = await AegisFlutter.bootstrap();
 
final product = EcommerceProduct(
  productId: 'sku-42',
  name: 'Cotton Tee',
  price: 1299.0,
);
await AegisFlutter.ecommerce.productViewed(product);
await AegisFlutter.ecommerce.addToCart(product);
await AegisFlutter.ecommerce.productWaitlisted(EcommerceWaitlist(
  product: product,
  channels: [WaitlistChannel.whatsapp],
));

identify() + group() run a Dart-side TraitGovernor that mirrors the cell-plane backend’s ingestion guards. NameGovernor + TraitGovernor run in Dart for early warnings; the actual transport stays on the native side.

Client-side governance details

The Dart TraitGovernor and NameGovernor share the same verdict codes + drift contract as the Android, iOS, React Native, and Web SDK implementations. Warnings surface as print() lines in debug mode, rate-limited to first 3 per (workspace, verdict) per session.

  • TraitGovernor — normalizes camelCase keys to snake_case, drops reserved-prefix keys (system., user., loyalty., cart., bill., $, _, …), truncates long strings, rejects oversized ones, and parses ISO-8601 / epoch on date-keyed fields. Drift contract: libs/mobile-sdk/tests/drift/trait-governor-verdicts.json.
  • NameGovernor — armed by the EventGovernanceHint returned from bootstrap(). Drops novel event names locally once your plan’s unique-event-name cap is hit (fails open during the 7-day grace window).

See Event governance → TraitGovernor for the full verdict matrix.

Push engagement reporting (SDK ≥0.5.0)

AegisFlutter.push posts push lifecycle events to the canonical ingestion endpoint via platform channels — the actual delivered / clicked / dismissed transport happens in the native iOS + Android SDKs, identical to standalone integrations.

import 'package:active_reach_sdk/active_reach_sdk.dart';
import 'package:active_reach_sdk/active_reach_sdk.dart';
 
// Register the device token from your push integration
// (firebase_messaging on Android + iOS).
await AegisFlutter.push.registerDeviceToken(token, platform: 'ios');
 
// push.delivered / .clicked / .dismissed fire automatically on the
// canonical /v1/push/engagement endpoint — nothing else to call from Dart.

Wire shape: POST /v1/push/engagement — see Event ingestion.

What’s next

Geofencing & locationPush primer