RiviumTrace Flutter SDK #

Flutter SDK for RiviumTrace error tracking platform. Supports Flutter Web, Mobile, and Chrome Extensions.

Features #

Simple Setup - Initialize with just a few lines of code
Multi-Platform - Works on Web, Android, iOS, and Chrome Extensions
Automatic Error Capture - Catches uncaught errors automatically
Manual Error Reporting - Capture custom errors and messages
Platform Detection - Automatically detects the running platform
Configurable - Flexible configuration options
Rich Context - Add custom data and context to errors

Supported Platforms #

Platform	Status	Notes
Flutter Web	Supported	Full support with JavaScript error catching
Chrome Extension	Supported	Optimized for extension environment
Android	Supported	Mobile error tracking
iOS	Supported	Mobile error tracking
Desktop	Supported	Windows, macOS, Linux

Installation #

Add this to your pubspec.yaml:

dependencies:
  rivium_trace_flutter_sdk: ^0.1.0

Run:

flutter pub get

Quick Start #

1. Initialize RiviumTrace (Basic) #

import 'package:flutter/material.dart';
import 'package:rivium_trace_flutter/rivium_trace.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  // Initialize RiviumTrace
  await RiviumTrace.init(RiviumTraceConfig(
    apiKey: 'rv_live_your_api_key_here',
    environment: 'production',
    release: '0.1.0',
  ));

  runApp(MyApp());
}

1b. Initialize RiviumTrace (Recommended - Better Error Catching) #

import 'package:flutter/material.dart';
import 'package:rivium_trace_flutter/rivium_trace.dart';

void main() async {
  // IMPORTANT: Initialize RiviumTrace FIRST, before WidgetsFlutterBinding
  await RiviumTrace.initWithZone(
    RiviumTraceConfig(
      apiKey: 'rv_live_your_api_key_here',
      environment: 'production',
      release: '0.1.0',
      captureUncaughtErrors: true,
    ),
    () async {
      // Move all initialization inside this callback
      WidgetsFlutterBinding.ensureInitialized();

      // Any other async initialization goes here
      // await Firebase.initializeApp();
      // await setupDatabase();

      runApp(MyApp());
    },
  );
}

2. Capture Errors Manually #

// Capture an exception
try {
  riskyOperation();
} catch (e, stackTrace) {
  await RiviumTrace.captureException(
    e,
    stackTrace: stackTrace,
    message: 'Failed to perform risky operation',
    extra: {'user_id': 'user123'},
  );
}

// Capture a custom message
await RiviumTrace.captureMessage(
  'User completed onboarding',
  extra: {'step': 'welcome_screen'},
);

Configuration Options #

RiviumTraceConfig(
  apiKey: 'rv_live_xxx',                            // Required (from RiviumTrace Console)
  environment: 'production',                        // Default: 'production'
  release: '0.1.0',                                 // Optional
  captureUncaughtErrors: true,                      // Default: true
  enabled: true,                                    // Default: true
  debug: false,                                     // Default: false
  timeout: 30,                                      // Default: 30 seconds
)

Note: The SDK automatically uses https://trace.rivium.co as the API endpoint. Get your API key from the RiviumTrace Console (format: rv_live_xxx or rv_test_xxx).

Platform-Specific Usage #

Chrome Extension #

void main() async {
  await RiviumTrace.init(RiviumTraceConfig(
    apiKey: 'rv_live_your_api_key',
    environment: 'production',
    debug: false, // Disable in production extensions
  ));

  runApp(MyExtensionApp());
}

Mobile App #

void main() async {
  await RiviumTrace.init(RiviumTraceConfig(
    apiKey: 'rv_live_your_api_key',
    environment: 'production',
    captureUncaughtErrors: true, // Recommended for mobile
  ));

  runApp(MyMobileApp());
}

Web App #

void main() async {
  await RiviumTrace.init(RiviumTraceConfig(
    apiKey: 'rv_live_your_api_key',
    environment: 'production',
    debug: kDebugMode, // Enable debug in development
  ));

  runApp(MyWebApp());
}

Advanced Usage #

Custom Error Context #

await RiviumTrace.captureException(
  exception,
  extra: {
    'user_id': 'user123',
    'feature': 'shopping_cart',
    'action': 'checkout',
    'cart_items': 5,
    'total_amount': 99.99,
  },
);

Conditional Error Reporting #

// Only report errors in production
if (kReleaseMode) {
  await RiviumTrace.captureException(error);
}

Cleanup (Important for Crash Detection) #

@override
void dispose() {
  RiviumTrace.close(); // Clean up resources and mark app as closed gracefully
  super.dispose();
}

Note: Calling RiviumTrace.close() is important for native crash detection. It marks the app as closing gracefully. If the app crashes without calling this, RiviumTrace will detect it on the next launch.

Error Information Captured #

The SDK automatically captures:

Error Message - Exception message or custom message
Stack Trace - Full stack trace for debugging
Platform - Detected platform (flutter_web, flutter_android, etc.)
Environment - Environment name (production, development, etc.)
Release - App version/release identifier
Timestamp - When the error occurred
User Agent - Browser/device information (web only)
URL - Current page URL (web only)
Custom Context - Any additional data you provide

Best Practices #

1. Initialize Early #

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await RiviumTrace.init(config); // Initialize before runApp
  runApp(MyApp());
}

2. Use Environments #

RiviumTraceConfig(
  apiKey: 'rv_live_your_api_key',
  environment: kDebugMode ? 'development' : 'production',
  debug: kDebugMode,
)

3. Add Context to Errors #

await RiviumTrace.captureException(
  error,
  extra: {
    'user_id': currentUser.id,
    'screen': 'checkout',
    'timestamp': DateTime.now().toIso8601String(),
  },
);

4. Handle Network Errors Gracefully #

try {
  await apiCall();
} catch (e) {
  if (e is SocketException) {
    // Handle network errors differently
    await RiviumTrace.captureMessage('Network error occurred', extra: {
      'error_type': 'network',
      'endpoint': '/api/data',
    });
  } else {
    await RiviumTrace.captureException(e);
  }
}

Crash Handling #

Universal Error Coverage for ALL Apps #

RiviumTrace provides comprehensive error detection for any Flutter app, regardless of what libraries or native code you use. Works for all companies, all apps, all use cases.

Types of Errors Captured #

Dart Exceptions - Captured in real-time
- Unhandled exceptions
- Flutter framework errors
- Widget build errors
Async Errors - Captured in real-time (with initWithZone)
- Uncaught async exceptions
- Future rejections
Platform Exceptions - Captured in real-time
- Errors from native platform channels
- Method channel errors
Native Crashes - Detected on next app launch (Universal)
- ANY database (SQLite, ObjectBox, Realm, Hive, Drift, etc.)
- ANY plugin (Camera, Location, Firebase, Maps, etc.)
- ANY native library (C/C++/Kotlin/Swift/Rust code)
- System crashes (SIGABRT, SIGSEGV, SIGILL, SIGFPE, OOM)
- All platforms (Android, iOS, macOS, Windows, Linux)

Native Crash Detection (Works for ANY Crash Source) #

Native crashes from any library or source cannot be caught in real-time because they kill the entire process immediately. However, RiviumTrace universally detects them on the next app launch:

When your app starts, RiviumTrace creates a crash marker file
If the app closes gracefully (via RiviumTrace.close()), the marker is removed
If the app crashes, the marker remains
On next launch, RiviumTrace detects the marker and sends a crash report

Example crash report:

{
  "message": "Native crash detected from previous session",
  "platform": "flutter_android",
  "crash_time": "2025-11-12T03:24:20.000Z",
  "extra": {
    "error_type": "native_crash",
    "time_since_crash_seconds": 293
  }
}

For Detailed Crash Handling Guide #

See CRASH_HANDLING.md for comprehensive documentation on:

How crash detection works
Best practices for maximum coverage
Debugging native crashes
Manual crash detection APIs

Development #

To contribute to this SDK:

Fork the repository
Create your feature branch
Write tests for your changes
Ensure all tests pass
Submit a pull request

License #

MIT License - see LICENSE file for details.

Support #

Documentation: RiviumTrace Docs
Issues: GitHub Issues
Email: support@rivium.co

rivium_trace_flutter_sdk 0.1.1 rivium_trace_flutter_sdk: ^0.1.1 copied to clipboard

Metadata