CDPGuidesSupport
SDKsClient

Flutter SDK (client)

Install the Ours Privacy Flutter SDK to capture privacy-first analytics in Flutter apps on iOS and Android. Pure Dart, with no IDFA and no ATT prompt on iOS.

Use the Ours Privacy Flutter SDK to track events, identify users, and collect app opens, sessions, and screens from your iOS and Android apps. It is pure Dart, so one package covers both platforms with no native setup.

Install

flutter pub add ours_privacy

Quick Start

Create one instance for your app and initialize it with your source's API token before runApp:

import 'package:flutter/widgets.dart';
import 'package:ours_privacy/ours_privacy.dart';

final op = OursPrivacy();

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await op.init('YOUR_API_TOKEN');
  runApp(const MyApp());
}

// Anywhere in your app
op.track('App Opened');

// After login
await op.identify({'externalId': 'user-123', 'email': 'user@example.com'});

Events are batched and sent every 10 seconds. Call await op.flush() to send them immediately, and await op.reset() on logout to start a new visitor. For default properties, a custom server URL, and the rest of the API, see the README on GitHub.

If your app asks for consent first, start opted out and opt in once the person agrees:

await op.init('YOUR_API_TOKEN', optOutTrackingByDefault: true);

// When consent is granted
await op.optInTracking();

optOutTrackingByDefault applies only until a choice is saved, so a returning user keeps the choice they made. While opted out, the SDK sends nothing. await op.optOutTracking() also clears unsent events, and the next opt-in starts a new session.

App lifecycle and screens

Turn on automatic lifecycle tracking to fill in app opens, sessions, and engagement in Mobile Analytics. It is off by default. Pass your app's version and build so you can follow release adoption:

await op.init(
  'YOUR_API_TOKEN',
  trackAutomaticEvents: true,
  appVersion: '2.0.0',
  appBuild: '42',
);
EventWhen it is sentEvent-specific properties
$mobile_first_openFirst tracked app open for this installation and sourceNone
$mobile_app_openEach tracked foreground entryNone
$mobile_session_startFirst tracked open in a new sessionNone
$mobile_session_engagementA foreground-time checkpoint, screen change, or background transitionengagement_duration_ms; screen_name when known
$mobile_session_endWhen an expired session is observed, when possibleNone
$mobile_app_updateFirst tracked open after the app version or build changesprevious_app_version and previous_app_build when known
$mobile_screen_viewYour app calls trackScreen() for a new visible screenscreen_name

A session continues when the app returns to the foreground within 30 minutes, and counts as engaged after 10 seconds in the foreground. $mobile_session_end is best effort, because an app can close without warning.

The SDK follows foreground and background changes on its own, but it does not see your navigator's route changes, so pass them in. With Navigator or MaterialApp named routes, add a NavigatorObserver that calls trackScreen() as routes change:

class OursScreenObserver extends NavigatorObserver {
  static const screenLabels = {'/': 'Home', '/schedule': 'Schedule'};

  void _trackScreen(Route<dynamic>? route) {
    final label = screenLabels[route?.settings.name];
    if (label != null) op.trackScreen(label);
  }

  @override
  void didPush(Route<dynamic> route, Route<dynamic>? previousRoute) => _trackScreen(route);

  @override
  void didPop(Route<dynamic> route, Route<dynamic>? previousRoute) => _trackScreen(previousRoute);

  @override
  void didReplace({Route<dynamic>? newRoute, Route<dynamic>? oldRoute}) => _trackScreen(newRoute);
}

MaterialApp(navigatorObservers: [OursScreenObserver()], routes: appRoutes);

Pass a fixed label from a list in your app, such as Schedule: up to 80 characters, starting with a letter, using only letters, numbers, spaces, underscores, and hyphens. trackScreen() throws for any other label, so map route names to labels as above rather than passing them through. Never build a label from a URL, route parameter, patient detail, or screen content.

Manual track() and trackScreen() calls work whether or not lifecycle tracking is on. Send standard healthcare events with the same names and properties as your other sources.

Lifecycle and screen events carry device, OS, and app version details, but not your default properties or link attribution. Keep each event under 196 of your own properties and 1 MB; a larger event is still sent, but it doesn't appear in Mobile Analytics.

Web-to-app identity

When your app is opened by a link carrying ours_visitor_id, the SDK sets that visitor ID so later events land on the same visitor profile as their web activity. It also reads supported UTM parameters and ad-platform click IDs from the link, attaches them to the events you track afterward, and sends a $deep_link_opened event with those values (not the raw URL).

Hand the URL over with await op.trackDeepLink(url), and await it before your next track() so the visitor ID and attribution apply first. If your app already holds the visitor ID, from a WebView or a platform channel, set it directly with await op.setVisitorId('550e8400-e29b-41d4-a716-446655440000'). To pass the visitor ID to another SDK, such as a mobile measurement partner, read it with op.getVisitorId().

The SDK hooks nothing in the operating system, so your app has to hand over the URL it was opened with, on a cold start and on a warm open. With the app_links package:

import 'package:app_links/app_links.dart';

// Delivers the link that started the app, then each later link
AppLinks().uriLinkStream.listen((uri) async {
  await op.trackDeepLink(uri.toString());
});

The UTM parameters and click IDs from a link last until the app quits; only the visitor ID persists across a restart. Pass the link to the SDK before you track an event that needs its attribution. Keep patient details out of the links you send people.

Mobile app attribution covers how app attribution works end to end, and when you need a mobile measurement partner alongside it.

Compatibility

  • Flutter 3.13 or later (Dart 3.1 or later)
  • iOS and Android apps

Because the SDK is pure Dart, iOS and Android version support follows your Flutter version. No IDFA is collected, so AppTrackingTransparency (ATT) permission is not required on iOS.

Need Help?

Next Steps

How is this guide?

On this page