uptimemesh_flutter 1.2.10

UptimeMesh Flutter SDK — crash, performance and network monitoring.

uptimemesh_flutter

Flutter SDK for UptimeMesh — automatic crash reporting, session tracking, screen analytics, network monitoring and custom event tracking.

Features

• Automatic crash reporting — FlutterError.onError + PlatformDispatcher.onError
• Session tracking — device model, OS, app version, network type, duration
• User identification — associate sessions with users via identify()
• Screen tracking — automatic via NavigatorObserver
• Network monitoring — HTTP request tracking with status code & duration
• Click tracking — trackClick() shortcut for button/element taps
• Custom events — track any user action with properties
• Offline buffer — SharedPreferences persistence, auto-retry on reconnect
• AdBlocker bypass — custom proxy endpoint support via ingestUrl
• Null-safe — Dart 3 / Flutter 3+

Installation

Add to pubspec.yaml:

dependencies:
  uptimemesh_flutter: ^1.2.8

Then:

flutter pub get

Quick Start

// main.dart
import 'package:flutter/material.dart';
import 'package:uptimemesh_flutter/uptimemesh_flutter.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await UptimeMesh.init('YOUR_API_KEY');
  runApp(const MyApp());
}

Get your API key from UptimeMesh dashboard → Mobil Uygulamalar → [App] → Entegrasyon.

---

API Reference

await UptimeMesh.init(apiKey, [options])

Initialize the SDK. Must be called after WidgetsFlutterBinding.ensureInitialized(). Calling more than once is a no-op.

await UptimeMesh.init(
  'YOUR_API_KEY',
  const UptimeMeshOptions(
    debug: true,
    flushInterval: Duration(seconds: 30),
    maxQueueSize: 50,
    // AdBlocker bypass: use your own proxy
    // ingestUrl: 'https://yourdomain.com/um-proxy',
  ),
);

Option	Type	Default	Description
ingestUrl	String?	https://ingest.uptimemesh.com	Custom ingest endpoint (AdBlocker bypass)
flushInterval	Duration	30 seconds	Auto-flush interval
maxQueueSize	int	50	Flush immediately when queue reaches this size
debug	bool	false	Print [UptimeMesh] logs to console
apiUrl	String?	—	Deprecated — use ingestUrl

---

UptimeMesh.identify(userId)

Associate the current session with a user. Appears as Kullanıcı in the Sessions table.

// After login
UptimeMesh.identify(user.id);   // ID, email or username

// After logout
UptimeMesh.identify(null);

---

Automatic Screen Tracking

Add UptimeMesh.navigatorObserver to MaterialApp:

MaterialApp(
  navigatorObservers: [UptimeMesh.navigatorObserver],
  routes: {
    '/': (_) => const HomeScreen(),
    '/profile': (_) => const ProfileScreen(),
  },
)

For GoRouter:

GoRouter(
  observers: [UptimeMesh.navigatorObserver],
  routes: [ /* ... */ ],
)

---

UptimeMesh.trackScreen(name)

Manual screen tracking.

UptimeMesh.trackScreen('HomeScreen');

---

UptimeMesh.trackClick(elementName, {screen?})

Log a button or element tap. Shortcut for trackEvent('click', {element, screen}).

UptimeMesh.trackClick('checkout_button', screen: 'CartScreen');
UptimeMesh.trackClick('menu_item_profile');

Shows up in the dashboard as a click event with the element name visible in breadcrumbs.

---

UptimeMesh.trackEvent(name, properties?)

Track custom events with optional properties.

UptimeMesh.trackEvent('purchase_completed', {
  'amount': 99.90,
  'currency': 'TRY',
  'product_id': 'plan_pro',
});

---

UptimeMesh.captureError(error, stackTrace?)

Manually report a caught (non-fatal) error.

try {
  await loadData();
} catch (e, stack) {
  UptimeMesh.captureError(e, stack);
}

---

Network Monitoring

Use UptimeMesh.httpClient as a drop-in replacement for http.Client:

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

For Dio, call UptimeMesh.trackNetwork() from an interceptor:

UptimeMesh.trackNetwork(
  url: UptimeMesh.sanitizeNetworkUrl(response.requestOptions.uri.toString()),
  method: response.requestOptions.method,
  statusCode: response.statusCode,
  durationMs: elapsed,
);

---

await UptimeMesh.flush()

Immediately send all queued events.

await UptimeMesh.flush();

---

Error Boundary (Recommended)

Wrap your app with runZonedGuarded to catch async errors outside the Flutter framework:

void main() {
  runZonedGuarded(() async {
    WidgetsFlutterBinding.ensureInitialized();
    await UptimeMesh.init('YOUR_API_KEY');
    runApp(const MyApp());
  }, (error, stack) {
    UptimeMesh.captureError(error, stack);
  });
}

---

AdBlocker Bypass (Proxy)

If your users have ad-blockers that block ingest.uptimemesh.com, set up a proxy on your own domain:

nginx:

location /um-proxy/ {
    proxy_pass https://ingest.uptimemesh.com/;
}

Then initialize with ingestUrl:

await UptimeMesh.init(
  'YOUR_API_KEY',
  const UptimeMeshOptions(ingestUrl: 'https://yourdomain.com/um-proxy'),
);

---

What's Collected Automatically

Data	Source
Flutter framework errors	FlutterError.onError
Dart async / platform errors	PlatformDispatcher.onError
Device model	device_info_plus
OS version	device_info_plus
App version + build number	package_info_plus
Network type (wifi/cellular)	connectivity_plus
Session duration	Lifecycle observer

---

Event Types

Type	Description	Triggered By
crash	Unhandled fatal error	Framework hooks
error	Caught / non-fatal error	captureError()
screen	Screen view	navigatorObserver / trackScreen()
event	Custom user action	trackEvent() / trackClick()
network	HTTP request	httpClient / trackNetwork()

---

Offline Mode

Events are persisted to SharedPreferences when offline. On the next app launch they are loaded and sent automatically.

---

Troubleshooting

Events not showing up?

1. Enable debug: true — look for [UptimeMesh] prints
2. Check your API key in the dashboard
3. Call await UptimeMesh.flush() to force send immediately

init() throws?

• Make sure WidgetsFlutterBinding.ensureInitialized() is called before init()

Screen tracking not working?

• Ensure UptimeMesh.navigatorObserver is in navigatorObservers
• Named routes must be set — unnamed routes have no route.settings.name

Data goes to ingest.uptimemesh.com but gets blocked?

• Use ingestUrl to point to your own proxy endpoint

---

Changelog

1.2.8

• README and changelog kept up to date with latest version

1.2.7

• Fix: inactive state now handled — iOS notification banners, Control Center and permission dialogs caused inactive→resumed cycles that created spurious new sessions
• Fix: Replaced bg==null session-creation logic with an explicit _needsNewSession flag — a new session is only opened after a real grace-period expiry or app detach

1.2.6

• Fix: flush() called immediately on paused — iOS suspends the Dart isolate before the 30s timer fires; events are now persisted even if the process is killed

1.2.5

• Fix: Future.delayed replaced with cancellable Timer — multiple background/foreground cycles within 30s no longer left stale timers that fired at the wrong time and split sessions

1.2.4

• Feat: Session grace period (30s) — quickly backgrounding and returning no longer creates a new session; real app close (30s+ or detached) ends the session correctly

1.2.3

• Fix: resolvedIngestUrl getter collapsed to single line so // ignore: deprecated_member_use_from_same_package covers the apiUrl reference (CI flutter analyze fix)

1.2.2

• Feat: UptimeMesh.trackClick(elementName, {screen?}) — shortcut for button/element click events
• Feat: UptimeMeshOptions.ingestUrl — custom ingest endpoint for AdBlocker bypass
• Change: Default endpoint changed from api.uptimemesh.com → ingest.uptimemesh.com
• apiUrl deprecated

1.2.1

• Fix: _uuid() critical bug — timestamp-based calculation only produced 16 unique UUIDs; replaced with Random.secure()
• Fix: _endCurrentSession() now uses await _sender.flush() — session data no longer lost on background
• Fix: _sdkVersion synced with pubspec

1.2.0

• New: UptimeMesh.identify(userId) — associate sessions with a user; pass null to clear
• New: SessionData.userId field

1.1.1

• UptimeMesh.trackNetwork() — manual network event for Dio / custom HTTP clients
• sanitizeNetworkUrl() made public

1.0.0

• Initial release

---

License

MIT © UptimeMesh