# Flutter mobile

Download [submetry.dart](https://submetry.com/sdk/submetry.dart) into `lib/telemetry/submetry.dart`. This source adapter uses Dart’s `HttpClient` and injected persistent storage. There is no published pub.dev package. It targets Flutter iOS/Android; `dart:io` is not available in Flutter Web.

## Configure before user actions

Wrap your existing storage library with the two-method interface. For example, an existing SharedPreferences instance can be adapted as follows:

```dart
import 'telemetry/submetry.dart';

class TelemetryStorage implements SubmetryStorage {
  final SharedPreferences preferences;
  TelemetryStorage(this.preferences);
  @override
  Future<String?> getItem(String key) async => preferences.getString(key);
  @override
  Future<void> setItem(String key, String value) async {
    if (!await preferences.setString(key, value)) {
      throw StateError('Cannot persist telemetry');
    }
  }
}

final telemetry = await Submetry.configure(
  appId: 'YOUR_APP_ID',
  key: 'YOUR_PUBLIC_SUB_PK_KEY',
  storage: TelemetryStorage(preferences),
  platform: Platform.isIOS ? 'ios' : 'android',
  environment: kDebugMode ? 'debug' : 'production',
  userId: actualFinancialProviderUserId,
  context: {'app_version': appVersion, 'build': buildNumber},
);
```

Import `dart:io`, Flutter’s foundation library and your existing preferences package for the referenced host-app values/types. Newer preferences APIs can be wrapped with the same interface; do not replace your app’s existing storage solely for telemetry. Initialize once, outside widget `build`.

## Events, identity and lifecycle

```dart
await telemetry.onboardingStep(1, 'goal');
await telemetry.onboardingCompleted();
await telemetry.track('activation_completed');
await telemetry.paywallShown('onboarding');
await telemetry.track('generation_completed', {'style': 'kinetic'});
await telemetry.identify(actualFinancialProviderUserId);
```

`first_open` is persisted once per installation; configuration starts the initial session. Your lifecycle observer should call `startSession()` on later foreground entries and `flush()` before backgrounding. Record `purchase_completed` only on confirmed success; cancelled purchases and restores are separate actions. Keep the same identity as RevenueCat or Superwall. Set known TestFlight environments explicitly.

## Durable delivery

Events persist before upload and retain IDs through restarts/retries. Batches contain up to 20 events. Automatic retry uses exponential backoff up to five minutes and stops after eight consecutive failures until manual `flush()` or a new configuration. Invalid-payload batches are archived in storage under `submetry:APP_ID:rejected`. Corrupt persisted queues abort initialization without overwriting the saved data. Retire an instance with `stop()` and keep one active instance per app/storage key.

The Dart source has not been compiled or run on a Flutter device in this workspace. Validate it with your app’s analyzer/build, exercise a sandbox journey and verify HTTP 202 plus Submetry Events. Configure the separate [RevenueCat](https://submetry.com/docs/revenuecat.md) or [Superwall](https://submetry.com/docs/superwall.md) financial webhook. Native AdServices is automatic only in the Swift SDK.
