Flutter SDK

The ScryWatch Flutter SDK adds log monitoring and session tracking to your iOS and Android apps. It automatically detects device type and manages session IDs for you.

What you’ll need

• A ScryWatch project API key (see API Keys & Settings)
• Flutter 3.0+ and Dart 3.0+

Step 1: Add the dependency

In your pubspec.yaml:

dependencies:
  scrywatch: ^1.0.0

Then run:

flutter pub get

Step 2: Initialize the SDK

The SDK is a plain LogClient instance — create one and keep it around (e.g. as a singleton or via your DI container) rather than calling a static initializer:

import 'package:flutter/widgets.dart';
import 'package:scrywatch/log_client.dart';

late final LogClient logClient;

void main() {
  WidgetsFlutterBinding.ensureInitialized();

  logClient = LogClient(
    endpoint: 'https://api.scrywatch.com',
    apiKey: 'sw_your_api_key_here',
    service: 'my-flutter-app',
    environment: 'production',
  );

  runApp(MyApp());
}

The SDK automatically detects the device type (ios, android, macos, windows, linux) from the Flutter environment.

Step 3: Log events

// Info level
logClient.log(LogLevel.info, 'User signed in', metadata: {'userId': '1234'});

// Warning level
logClient.log(LogLevel.warn, 'Low memory warning', metadata: {'available_mb': 45});

// Error level
logClient.log(LogLevel.error, 'Payment failed', metadata: {'orderId': 'ord_abc', 'reason': 'card_declined'});

Events are buffered and flushed automatically — every 10 seconds, or immediately once the buffer reaches its max size (50 events by default). You don’t need to manage flushing manually, though you can force one with await logClient.flush().

Step 4: Track user sessions

Start and end sessions explicitly around the part of your app you want to trace:

// Start a session (generates a new session ID)
logClient.startSession();

// Associate the session with a specific user
logClient.setUserId('user_1234');

// End the session when it's done (flushes pending events)
logClient.endSession();

Session events appear on the Sessions page in the dashboard.

Step 5: Track navigation

In your route observer, add navigation tracking:

class ScryWatchNavigatorObserver extends NavigatorObserver {
  @override
  void didPush(Route route, Route? previousRoute) {
    logClient.logNavigation(route.settings.name ?? 'unknown');
  }
}

Register the observer in your MaterialApp:

MaterialApp(
  navigatorObservers: [ScryWatchNavigatorObserver()],
  ...
)

Step 6: Track API calls

final stopwatch = Stopwatch()..start();
final response = await http.get(Uri.parse('https://api.example.com/data'));
stopwatch.stop();

logClient.logApiCall('GET', '/data', response.statusCode, stopwatch.elapsedMilliseconds);

Step 7: Capture Flutter errors

Capture unhandled Flutter errors and send them to ScryWatch:

void main() {
  WidgetsFlutterBinding.ensureInitialized();

  logClient = LogClient(
    endpoint: 'https://api.scrywatch.com',
    apiKey: 'sw_your_api_key_here',
  );

  FlutterError.onError = (FlutterErrorDetails details) {
    logClient.logError(details.exception, details.stack);
  };

  runApp(MyApp());
}

Tip: Combine Flutter error capture with zone-based Dart error catching for complete coverage of both Flutter framework errors and async Dart errors.

Step 8: Capture async Dart errors

runZonedGuarded(() {
  runApp(MyApp());
}, (error, stackTrace) {
  logClient.logError(error, stackTrace);
});

Step 9: Clean up

If the LogClient no longer needs to run (e.g. in tests, or a short-lived isolate), call dispose() to cancel the flush timer, stop observing app lifecycle events, and flush any remaining buffered events:

logClient.dispose();

In a typical app, LogClient lives for the app’s whole lifetime and you don’t need to call this.

You’re done

You now know how to:

• Add the ScryWatch Flutter SDK to your project
• Initialize a LogClient with your API key and service name
• Log events with metadata
• Track user sessions, navigation, and API calls
• Capture unhandled Flutter and Dart errors

Related docs

Full Flutter SDK reference — constructor options, session management API, and automatic device detection fields.