Talaria
Docs

Flutter SDK

Quick setup for talaria_flutter — runZonedApp, the first error, routes, and screen heatmaps.

talaria_flutterdartinstalliniterrors

talaria_flutter (0.2.7) adds framework error hooks, zone bootstrap, navigator route tags, and screen heatmaps on top of talaria. It re-exports talaria. You do not add the core package unless a shared Dart library needs it on its own.

Quick setup

yaml
dependencies:
  talaria_flutter: ^0.2.7
dart
import 'package:flutter/material.dart';
import 'package:talaria_flutter/talaria_flutter.dart';

Future<void> main() async {
  await TalariaFlutter.runZonedApp(
    TalariaOptions(
      dsn: 'https://ingest.newtalaria.com',
      apiKey: const String.fromEnvironment('TALARIA_API_KEY'),
      release: const String.fromEnvironment('APP_RELEASE'),
      minLevel: SeverityLevel.warning,
    ),
    const MyApp(),
  );
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      navigatorObservers: [TalariaNavigatorObserver()],
      home: const HomePage(),
    );
  }
}
bash
flutter run \
  --dart-define=TALARIA_API_KEY=tal_live_… \
  --dart-define=APP_RELEASE=1.4.2+42

Then capture one error and flush:

dart
await Talaria.captureException(
  Exception('talaria hello'),
  stackTrace: StackTrace.current,
);
await Talaria.flush();

The key decides the environment. A local run uses a development key. Confirm with search_errors and environment: development. minLevel: warning drops info messages. captureException is an error, so Issues still shows it.

What you can do

Capability Where
Framework, platform, zone, and widget-build errors, plus logs and breadcrumbs Errors, logs, and breadcrumbs
Screen transactions and wrapHttpClient Instrumentation and tracing
Routes, setScreen, and screen heatmaps Navigation and screens
Analytics, feature flags, and consent Best practices

Tracing, analytics, and heatmaps follow Project configuration. Screen heatmaps need TalariaScreenCapture in the tree. Automatic screen views use the route name. Unnamed routes are skipped.

Install

yaml
dependencies:
  talaria_flutter: ^0.2.7

Then flutter pub get.

Initialization

runZonedApp wraps init and runApp in a zone and installs ErrorWidget.builder. You can call TalariaFlutter.init yourself and add the observer on the app. Either way, pass TalariaNavigatorObserver on MaterialApp or CupertinoApp.

A staging flavor uses a staging key. A production flavor uses a production key. Local runs use a development key and still send a version or SHA as release.

App init vs Project settings

App init (TalariaOptions) Project settings
dsn, apiKey, release, minLevel Tracing enabled and the traces sample rate
Tags, beforeSend Analytics and heatmaps

See Project configuration.

API key

tal_live_… keys are public client ingest credentials. Pass the key with --dart-define. The server stamps the key's environment on events, spans, analytics, and heatmaps. DSN for Talaria Cloud is https://ingest.newtalaria.com.

Verification

  1. Run with a valid development key.
  2. Trigger a framework error or call Talaria.captureException.
  3. Dashboard Issues (switch the shell to Development) or MCP search_errors / search_events.

Troubleshooting

See troubleshooting.