Flutter documentation

logwatcher_sdk — pure Dart (no Flutter SDK dependency): Flutter mobile/desktop and Dart CLI. Persistent JSONL queue, gzip batches. Flutter Web should use the JavaScript SDK.

Getting started

You need an application key. Create an account, add an app in the dashboard, and copy the key shown on its card. Every SDK call is tied to that key.

Install the SDK

Pure Dart package — add it to pubspec.yaml as a path or git dependency:

# pubspec.yaml
dependencies:
  logwatcher_sdk:
    path: path/to/client-sdks/flutter/logwatcher_sdk
  # for a persistent on-device queue:
  path_provider: ^2.0.0

Works on Flutter mobile/desktop and in Dart CLI apps. Flutter Web should use the JavaScript SDK instead (dart:io is unavailable there).

Initialize

Initialize in main(), before runApp(). URL overrides must come before init().

// Dart — in main(), before runApp()
import 'package:logwatcher_sdk/logwatcher_sdk.dart';
import 'package:path_provider/path_provider.dart';

LogWatcher.setApiUrl('https://fintechiq-logwatcher-19133922986.europe-west1.run.app');
await LogWatcher.init('YOUR_APP_KEY',
    enableCrashReporting: true,
    storageDirectory: await getApplicationSupportDirectory());

storageDirectory enables the persistent queue and a stable device identity; without it the queue is in-memory.

Send logs

One method per level. Logs are queued on-device and uploaded in batches; if the network is down they are retried later.

LogWatcher.d('PaymentFlow', 'card inserted · reading chip');
LogWatcher.i('PaymentFlow', 'auth approved · code 00');
LogWatcher.w('Network', 'settle latency 2.1s — retrying');
LogWatcher.e('PaymentFlow', 'auth declined · code 05');
LogWatcher.t('Lifecycle', 'didChangeAppLifecycleState'); // trace
LogWatcher.f('Watchdog', 'unrecoverable state');  // fatal

For full control there is also LogWatcher.log(line:, method:, file:, level:, tag:, text:) (named parameters).

The non-sequential wire values are part of the LogWatcher wire protocol — the SDK handles the mapping.

Crash reporting

Report errors explicitly, or hook Flutter's error channels once in main():

LogWatcher.recordError(error, stackTrace);          // one-off

// catch-all wiring:
FlutterError.onError = (details) =>
    LogWatcher.recordError(details.exception, details.stack);
PlatformDispatcher.instance.onError = (error, stack) {
  LogWatcher.recordError(error, stack);
  return true;
};

Breadcrumb logs are persisted (with storageDirectory) and upload on the next launch even after a hard crash.

Issues & user feedback

Report a noteworthy condition as an issue, or collect a message from the user. Each call returns a Uri? deep-linking to the item in your dashboard.

final url = LogWatcher.sendIssue('Sync failed', '3 retries exhausted on /settle');
LogWatcher.sendUserFeedback('From the merchant', 'Receipt printed twice today');

Device key-values

Attach searchable properties to a device — a store number, a merchant id, a build flavour:

LogWatcher.setDeviceString('store', 'ATH-0042');
LogWatcher.setDeviceInteger('lane', 2);
LogWatcher.setDeviceBoolean('pilot', true);
LogWatcher.removeDeviceKey('pilot');

Remote device control

On every launch the SDK registers the device and receives its remote flags. From the dashboard you can enable log collection for a single device (a misbehaving terminal) while the rest of the fleet stays quiet — no release, no restart loop. To force collection locally regardless of the remote flag:

LogWatcher.setForceEnabled(true);   // override the remote toggle
LogWatcher.forceSendOnce();          // flush the queue right now

Advanced options

Batches ≥1 KiB are gzip-compressed (Content-Encoding: gzip); the server accepts both gzip and raw JSON.