JustAnalytics/Documentation

JustAnalytics for Flutter

Step-by-step guide to add crash reporting, analytics, and performance monitoring to your Flutter app

JustAnalytics for Flutter

Add crash reporting, HTTP tracing, navigation tracking, and performance monitoring to your Flutter application.

Time to data: 5 minutes

Prerequisites#

Install the SDK

Add to your pubspec.yaml:

dependencies:
  justanalytics_flutter: ^0.1.0

Then install:

flutter pub get

Initialize the SDK

Initialize in your main() function and wrap your app to catch uncaught errors:

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

void main() {
  JustAnalytics.instance.init(JustAnalyticsOptions(
    siteId: 'site_abc123',
    apiKey: 'ja_sk_your_api_key_here',
    environment: const String.fromEnvironment('ENV', defaultValue: 'development'),
    release: '1.0.0',
  ));

  // Wrap with error catching — captures Flutter framework errors,
  // platform errors, and uncaught async errors
  JustAnalytics.instance.runApp(
    const MyApp(),
  );
}

Tip: Use --dart-define=ENV=production when building for production to set the environment.

Add navigation tracking

Add the navigation observer to your MaterialApp:

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

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'My App',
      navigatorObservers: [
        JustAnalyticsNavigationObserver(),
      ],
      home: const HomeScreen(),
    );
  }
}

For GoRouter:

final router = GoRouter(
  observers: [JustAnalyticsNavigationObserver()],
  routes: [
    GoRoute(path: '/', builder: (_, __) => const HomeScreen()),
    GoRoute(path: '/profile', builder: (_, __) => const ProfileScreen()),
  ],
);

Add HTTP tracing

Instrument your HTTP clients to trace outgoing requests:

Dio:

import 'package:dio/dio.dart';
import 'package:justanalytics_flutter/justanalytics_flutter.dart';

final dio = Dio();
dio.interceptors.add(JustAnalyticsDioInterceptor());

// All requests are now traced with W3C traceparent headers
final response = await dio.get('https://api.example.com/users');

package:http:

import 'package:http/http.dart' as http;
import 'package:justanalytics_flutter/justanalytics_flutter.dart';

final client = JustAnalyticsHttpClient(http.Client());

final response = await client.get(Uri.parse('https://api.example.com/users'));

Add error tracking

Capture handled exceptions explicitly:

try {
  await processPayment(orderId);
} catch (error, stackTrace) {
  JustAnalytics.instance.captureException(
    error,
    stackTrace,
    tags: {'module': 'payments', 'order_id': orderId},
  );
  // Show error to user
}

Verify Your Setup

Launch your app on a simulator or device, navigate between screens and make an HTTP request. Check the dashboard for screen view events and network traces.

Open Dashboard

Advanced Features#

Custom events#

JustAnalytics.instance.trackEvent('purchase_completed', {
  'orderId': 'o123',
  'total': 99.99,
  'items': 3,
});

JustAnalytics.instance.trackEvent('onboarding_step', {
  'step': 2,
  'stepName': 'profile_setup',
});

User identification#

// After login
JustAnalytics.instance.setUser(
  id: user.id,
  email: user.email,
  username: user.displayName,
);

Performance monitoring#

Measure app startup time and screen render duration:

// Mark app as ready (call after first frame renders)
JustAnalytics.instance.markAppReady();

// Measure screen render time
class _HomeScreenState extends State<HomeScreen> {
  late final String _renderId;

  @override
  void initState() {
    super.initState();
    _renderId = JustAnalytics.instance.startScreenRender('HomeScreen');
  }

  @override
  void didChangeDependencies() {
    super.didChangeDependencies();
    // End measurement after first build
    WidgetsBinding.instance.addPostFrameCallback((_) {
      JustAnalytics.instance.endScreenRender(_renderId);
    });
  }
}

Global tags#

JustAnalytics.instance.setTag('theme', 'dark');
JustAnalytics.instance.setTag('locale', 'en_US');

Capture messages#

JustAnalytics.instance.captureMessage(
  'User completed onboarding',
  level: 'info',
  tags: {'flow': 'onboarding'},
);

Flush before background#

import 'package:flutter/widgets.dart';

class AppLifecycleObserver extends WidgetsBindingObserver {
  @override
  void didChangeAppLifecycleState(AppLifecycleState state) {
    if (state == AppLifecycleState.paused) {
      JustAnalytics.instance.flush();
    }
  }
}

// Register in initState
WidgetsBinding.instance.addObserver(AppLifecycleObserver());

Clean shutdown#

// When disposing your app
JustAnalytics.instance.close();

Build configuration#

Pass credentials at build time with --dart-define:

flutter run \
  --dart-define=JA_SITE_ID=site_abc123 \
  --dart-define=JA_API_KEY=ja_sk_your_api_key \
  --dart-define=ENV=production

Then read them in code:

JustAnalytics.instance.init(JustAnalyticsOptions(
  siteId: const String.fromEnvironment('JA_SITE_ID'),
  apiKey: const String.fromEnvironment('JA_API_KEY'),
  environment: const String.fromEnvironment('ENV', defaultValue: 'development'),
));

Configuration options#

| Option | Type | Default | Description | |--------|------|---------|-------------| | siteId | String | required | Site ID from dashboard | | apiKey | String | required | API key (ja_sk_...) | | environment | String | 'production' | Deployment environment | | release | String | — | App version string | | debug | bool | false | Enable debug logging | | enabled | bool | true | Enable/disable SDK |