Flutter

Requirements

• Flutter 3.44 or later (Dart 3.10 or later). Flutter uses Swift Package Manager by default from 3.44, and the Apple SDK is a Swift package only: there is no podspec.
• iOS 15 or later; Android 7.0 (API level 24) or later.
• No other platform: on web and desktop every call does nothing.

Install

dependencies:
  apsio_flutter:
    git:
      url: https://github.com/Apsio/apsio-flutter-sdk.git
      ref: v0.1.0

• iOS. The plugin is a Swift package that pulls the Apple SDK from GitHub. The Apple SDK links KSCrash through Swift Package Manager: an app that also pulls KSCrash through CocoaPods (some crash reporters vendor it) gets duplicate symbols.
• Android. The plugin adds Apsio’s Maven repository to the app’s projects and depends on io.apsio:apsio-android. An app with minSdk under 26 turns on core library desugaring, as for the Android SDK.

Start

import 'package:apsio_flutter/apsio_flutter.dart';
import 'package:flutter/material.dart';

Future<void> main() async {
  await Apsio.start(const ApsioKey.perPlatform(ios: 'a-…', android: 'a-…'));
  runApp(
    MaterialApp(
      navigatorObservers: [ApsioNavigatorObserver()],
      home: const HomePage(),
    ),
  );
}

Options

What is recorded

• Errors the framework catches (FlutterError.onError), such as an exception in a build method, and uncaught Dart errors (PlatformDispatcher.onError), as handled errors with their Dart stacks. A Dart error does not end the process, so it is not a crash; native crashes are crashes. The app’s own handlers still run.
• Screens from ApsioNavigatorObserver, or from Apsio.trackScreen.
• Network requests on iOS that go through URLSession, such as with package:cupertino_http, as client spans recorded by the Apple SDK. Requests made with dart:io’s HttpClient, and so with package:http on its default client, are not recorded.

Users, logs, errors and spans

Apsio.setUser(idHash);                           // HMAC of the id with an app secret; never an email
Apsio.clearUser();                               // when the user signs out
Apsio.setAttribute('plan', 'pro');               // on every record; null removes it
Apsio.log(Severity.info, 'Checkout opened', attributes: {'cart.items': 3});
Apsio.addBreadcrumb('Tapped pay');

try {
  await pay();
} catch (error, stack) {
  Apsio.recordError(error, stack: stack, fingerprint: 'checkout-card-declined');
}

final span = Apsio.startSpan('checkout.submit');
final child = Apsio.startSpan('checkout.validate'); // nests under the innermost open span
child.end();
span.end(error: true);                           // an error status
await Apsio.withSpan('checkout.submit', (s) => submit());

Apsio.setFeatureFlag('new-checkout', 'b');
Apsio.trigger('checkout_failed');                // fires the trigger event:checkout_failed
Apsio.setConsent(false);                         // stops collection, drops what is queued
await Apsio.flush();                             // sends what is queued now

• The user hash follows the native SDKs’ rules: see The user hash.
• recordError takes the stack from the catch; without one, an Error’s own stack is used, else the stack where it is called. fingerprint replaces the grouping.
• Spans. A span’s parent is parent when given, otherwise the enclosing withSpan, which stays the parent across awaits, otherwise the innermost span still open; root: true makes a root span. withSpan ends its span when the operation settles, with an error status if it throws. Spans started before start completes are not recorded, and Dart spans never parent native work, such as network requests.
• Calls before and during start. Every call is safe at any time: before start it does nothing, calls made while start runs are applied once it completes, in order, up to 256, and a failure inside the SDK is never thrown into the app. setConsent called before start applies from the start.
• Attribute values are strings, booleans, numbers and lists of strings; anything else is dropped, never sent as its string form.

Screens

ApsioNavigatorObserver(
  screenName: (route) => route is PageRoute ? route.settings.name : null,
)

Dart errors

• Redaction works as for a native handled error: redact covers its attributes, and listing exception.message covers the message and the record’s body. The type and the stack are never redacted: a stack holds function names and file names, with no local paths.
• Messages. A value thrown that is neither an Error, an Exception nor a string is described by its type, never serialized. A FormatException leaves out its source, a FlutterError sends its one-line summary, and a URL in a message loses its query and fragment.
• Isolates. Errors in an isolate you spawn are not caught: send them to Apsio.recordError.

Symbols for Dart stacks

• Without --split-debug-info, the stack names its functions, files and lines (#0 Checkout.pay (package:shop/checkout.dart:12:3)). Apsio reads it as it is, with nothing to upload.
• With --split-debug-info, which --obfuscate requires, the stack holds the build’s build_id and an address per frame instead. Apsio resolves those addresses with the build’s debug file, the app.<platform>-<arch>.symbols file Flutter writes into the --split-debug-info directory: on Android an ELF file whose GNU build id is the stack’s build_id, on iOS a Mach-O file whose UUID is the build_id. The names in that file stay readable under --obfuscate, so frames need no obfuscation map.

Privacy and consent

What this version does not do

• No session replay, and no option for it. Flutter draws its own pixels, so the native view tree shows one flat surface, and a wireframe replay needs a walk of the widget tree that does not exist yet. Masking fails closed, so there is no replay rather than a partial one. If you start the native SDK yourself, leave its replay option off too.
• No live inspection, for the same reason: its wireframes need that walk.
• No spans for Dart’s HTTP requests. dart:io’s HttpClient has its own sockets, so the native SDKs do not see it. package:cupertino_http goes through URLSession, which the Apple SDK does see.
• Slow and frozen frames are not Flutter’s. The native SDKs count what their platform reports for the window; Flutter’s frame timings do not reach them yet.
• Dart stacks from a build with --split-debug-info are not symbolicated yet: their debug files cannot be uploaded (see Symbols for Dart stacks). On iOS, a release stack’s build_id has not yet been compared with the Mach-O UUID of its debug file on a real device, so that match is unproved.
• No log bridge for print or debugPrint: use Apsio.log.
• Errors in isolates you spawn are not caught: send them to Apsio.recordError.

Next

• Upload your dSYMs and Android mappings, for native frames.
• Remote configuration: sampling and capture without a release.
• The API reference of the package.