Accès anticipéSur invitation, et les SDK ne sont pas encore publiés.Demander une invitation
Aller au contenu
Docs

Flutter

Des logs structurés depuis votre app Flutter sur iOS et Android, par-dessus les SDK natifs de Lyrelog.

Apps iOS et Android, par-dessus les SDK natifs

Le SDK Flutter est le package Dart lyrelog, un plugin pour iOS 16 et Android 7.0 (API 24) ou plus récent, compilé avec Flutter 3.50. C'est une fine couche Dart par-dessus les SDK natifs, le SDK Swift sur iOS et le SDK Android sur Android : la file sur disque, les plantages natifs, l'envoi en arrière-plan, les sessions, le consentement et les événements vérifiés fonctionnent donc comme là-bas. En plus, il remonte les erreurs Dart que personne n'a interceptées et nomme les écrans à partir de votre navigator.

Préversion interne : ce package n'est pas encore publié. D'ici là, flutter pub add lyrelog ne trouve rien : il n'est pas sur pub.dev, et le dépôt est privé et n'a encore aucune release.

Installation

flutter pub add lyrelog

Ou dans pubspec.yaml :

dependencies:
  lyrelog: ^0.1.0

Configuration iOS

  • Le plugin est un package Swift : votre app le compile donc avec Swift Package Manager, que Flutter utilise par défaut. Il n'existe pas de version CocoaPods.
  • Réglez le minimum de l'app sur iOS 16 : dans Xcode, la target Runner, General, Minimum Deployments (IPHONEOS_DEPLOYMENT_TARGET = 16.0). La valeur par défaut de Flutter est plus basse, et le build s'arrête avec un message qui le signale.

Configuration Android

  • Les valeurs par défaut de Flutter conviennent : compileSdk 36 et Kotlin 2.2 ou plus récent. minSdk peut rester à 24.

La bibliothèque ajoute la permission INTERNET au manifeste de votre app.

Démarrage

Démarrez une seule fois, le plus tôt possible : dans main, avant runApp. Un second appel pendant qu'il tourne est ignoré. start appelle lui-même WidgetsFlutterBinding.ensureInitialized(), il peut donc venir en premier, et rien n'a besoin de l'attendre : ce que vous journalisez après start atteint le SDK natif après lui. Les événements journalisés avant start sont ignorés, mais setUser et setConsent appelés avant start sont conservés et appliqués au démarrage.

import 'package:flutter/widgets.dart';
import 'package:lyrelog/lyrelog.dart';

void main() {
  Lyrelog.start(const LyrelogConfiguration(
    apiKey: 'lyr_ing_...', // ingest-only: it can append events, never read them
  ));
  runApp(const MyApp());
}

Les événements partent vers https://ingest.lyrelog.com. Ne passez endpoint que pour les envoyer ailleurs. C'est l'URL de base (un chemin .../v1/events:batch collé est retiré) et elle doit être en https ; le http simple ne fonctionne que pour localhost, 127.0.0.1 ou ::1, et sur l'émulateur Android pour 10.0.2.2 (voir En développement et dans les tests). Avec tout autre endpoint, rien n'est envoyé et les événements restent sur l'appareil.

Journaliser des événements

Une fonction par niveau : trace, debug, info, notice, warning, error, critical, ou log(level, message, ...) avec un LogLevel.

Lyrelog.info('checkout_done', attrs: {'items': 3, 'latency_ms': ms});
Lyrelog.error('payment_declined', category: 'checkout',
    attrs: {'code': 51}, payload: {'response': raw});

Les attributs sont une Map<String, Object?> : chaînes, nombres, booléens, null, listes et maps imbriquées jusqu'à 4 niveaux. Un DateTime est envoyé en texte ISO 8601, une Duration en millisecondes, un enum par son nom, et tout le reste par son toString(). Le payload est n'importe quelle valeur de ces types, pour le détail que vous ne lisez qu'en ouvrant un événement.

Un logger par domaine

Un logger appose sa category sur chaque événement, comme un tag de log. Il a tous les niveaux, plus log et captureError. Il est peu coûteux à créer et à conserver, et journalise dans le SDK en cours d'exécution au moment de l'appel.

final sync = Lyrelog.logger('sync');
sync.warning('sync_conflict', attrs: {'records': 2});

Utilisateurs

Lyrelog.setUser(account.id); // attached to every following event
Lyrelog.setUser(null);       // on sign-out

await Lyrelog.sessionId() donne l'id de la session en cours, par exemple pour l'afficher dans un écran d'assistance.

L'id utilisateur n'est pas conservé d'un lancement à l'autre : appelez de nouveau setUser à chaque lancement, dès que vous savez de qui il s'agit.

Écrans

Indiquez où se trouve la personne. Lyrelog journalise screen_viewed (domaine navigation) avec l'écran précédent et les secondes passées dessus, et marque chaque événement suivant d'un attribut screen.

Ajoutez LyrelogNavigatorObserver au navigator de votre app : chaque route de page qui passe au premier plan devient un écran, nommé d'après le nom de sa route :

MaterialApp(
  navigatorObservers: [LyrelogNavigatorObserver()],
  routes: {
    '/': (_) => const HomePage(),
    '/settings': (_) => const SettingsPage(),
  },
)

Cela fonctionne avec n'importe quel Navigator, donc aussi avec un routeur qui accepte des observers (avec go_router, GoRouter(observers: [LyrelogNavigatorObserver()], ...)). Revenir à une page la journalise de nouveau, puisqu'elle redevient l'écran affiché. Les boîtes de dialogue, bottom sheets et menus ne changent pas l'écran, et les routes sans nom sont ignorées. Vous pouvez changer l'un comme l'autre :

LyrelogNavigatorObserver(
  nameExtractor: (settings) => settings.name?.replaceFirst('/', ''), // null or '' skips the route
  routeFilter: (route) => route is PageRoute,                         // which routes are screens
)

Ou appelez la fonction vous-même :

Lyrelog.screen('Settings');

L'événement porte screen, previous_screen et seconds_on_previous. Rappeler screen avec le même nom ne journalise rien. screen accepte des attrs supplémentaires pour l'événement screen_viewed. Désactivez le marquage avec attachScreen: false.

Les erreurs que vous interceptez

try {
  await store.purchase(product);
} catch (e, s) {
  Lyrelog.captureError(e, stackTrace: s, category: 'store');
}

Cela envoie l'événement exception qu'envoient tous les SDK : niveau error, les attributs error_type (le type à l'exécution) et error_message (son toString()), et un payload avec la description et jusqu'à 60 frames de la stack. Sans stackTrace, les frames sont la stack propre d'une Error, si elle en a une. attrs ajoute les vôtres ; level change le niveau. Chaque logger a aussi captureError.

Erreurs et plantages

Les erreurs Dart que personne n'intercepte

start les remonte de lui-même (captureErrors, activé par défaut), sous forme d'événements exception avec handled: false et un mechanism qui indique où Flutter les a transmises :

mechanismOrigineLe payload contient aussi
flutter_errorFlutterError.onError : les erreurs pendant la construction, la mise en page ou le dessin des widgets, et dans les callbacks de gesteslibrary (widgets library) et context (building MyWidget)
platform_dispatcherPlatformDispatcher.instance.onError : les erreurs dans le code asynchrone, les timers et les futures que personne n'a attendues

Les handlers déjà en place continuent de s'exécuter, après ceux de Lyrelog, et PlatformDispatcher.onError renvoie ce que renvoyait le précédent (sans handler précédent, Flutter affiche quand même l'erreur). Si vous définissez vos propres handlers, définissez-les avant start, ou appelez captureError depuis ceux-ci.

Au plus 10 de ces erreurs sont envoyées par minute, et la même erreur (son type, son message et sa première frame) une seule fois toutes les 10 secondes : une erreur de mise en page qui se répète à chaque frame n'envoie donc qu'un événement. Les erreurs que Flutter marque comme silencieuses, qu'il ne remonte pas non plus dans les builds de release (une image qui n'a pas pu se charger, par exemple), sont laissées de côté.

Une erreur Dart ne termine pas une app Flutter : ce sont donc des événements exception, jamais app_crashed.

Si votre app tourne dans sa propre zone, remontez les erreurs de la zone de la même façon :

runZonedGuarded(() => runApp(const MyApp()), (error, stack) {
  Lyrelog.captureError(error, stackTrace: stack, handled: false, mechanism: 'zone');
});

Plantages natifs

Les plantages de l'app elle-même viennent des SDK natifs (captureNativeCrashes, activé par défaut). Ils sont envoyés au lancement suivant, datés du moment où ils se sont produits, dans le domaine diagnostics :

PlateformeÉvénementsOrigine
iOSapp_crashed (critical), app_hung (error), cpu_overuse, disk_write_overuse, slow_launch (warnings)MetricKit, comme sur la page Swift
Androidapp_crashed (critical) avec handled: false et mechanism: uncaught_exceptionLes exceptions JVM non interceptées, comme sur la page Android

Sur Android, les plantages natifs (C ou C++) et les ANR ne sont pas remontés.

Builds obfusqués

Avec flutter build --obfuscate --split-debug-info=<dir>, les noms de types dans error_type et les frames sont obfusqués. Gardez les symboles que le build écrit et lancez flutter symbolize avec eux sur les frames pour les lire.

Environnements et plateforme

Le SDK natif choisit l'environnement au démarrage :

  • iOS : development pour un build de debug, tout build sur le simulateur, ou un build avec un profil de provisionnement intégré (signature de développement et ad hoc) ; testflight pour un build TestFlight ; production sinon. Ensuite, la réponse de StoreKit, comme sur la page Swift.
  • Android : development quand l'app est débogable (tout build de debug), production sinon.

Vos propres builds flutter run envoient development, alors que le tableau de bord s'ouvre sur production : choisissez development dans la barre du haut pour les voir.

La plateforme est l'OS, ios ou android : un seul projet accueille donc les deux, et le tableau de bord peut filtrer sur chacune. Vous pouvez remplacer l'un ou l'autre dans la configuration :

LyrelogConfiguration(
  apiKey: key,
  environment: isInternalTester ? 'internal' : null, // null = detected
  platform: null,
)

N'importe quel nom convient : lettres minuscules, chiffres, - et _, jusqu'à 32 caractères. Tout autre texte est transformé en nom valide (Staging EU devient staging-eu).

Lyrelog.start(LyrelogConfiguration(apiKey: key, consent: Consent.pending));
// later, when the person chooses:
Lyrelog.setConsent(Consent.granted); // sends, including what was kept while pending
Lyrelog.setConsent(Consent.denied);  // deletes everything and stops recording

Consent.pending garde les événements sur l'appareil sans les envoyer. Rien n'est envoyé tant que le consentement n'est pas accordé, y compris ce qu'un lancement précédent a laissé. Démarrer avec Consent.denied supprime tout ce qui reste en file depuis un lancement précédent ainsi que l'id d'installation, et n'enregistre rien. Un setConsent appelé avant start l'emporte sur le consent de la configuration.

Le consentement n'est pas conservé d'un lancement à l'autre : stockez vous-même le choix de la personne et passez-le à start à chaque fois.

Une app complète

Démarrez avec le consentement stocké, définissez la personne quand elle se connecte et nommez les écrans à partir du navigator :

import 'package:flutter/material.dart';
import 'package:lyrelog/lyrelog.dart';
import 'package:shared_preferences/shared_preferences.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  final prefs = await SharedPreferences.getInstance();
  final consent = switch (prefs.getString('diagnostics')) {
    'granted' => Consent.granted,
    'denied' => Consent.denied,
    _ => Consent.pending,
  };
  Lyrelog.start(LyrelogConfiguration(apiKey: 'lyr_ing_...', consent: consent));
  runApp(const MyApp());
}

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

  @override
  Widget build(BuildContext context) => MaterialApp(
        navigatorObservers: [LyrelogNavigatorObserver()],
        routes: {
          '/': (_) => const HomePage(),
          '/sign-in': (_) => SignInPage(onSignedIn: signedIn),
        },
      );
}

void signedIn(Account account) {
  Lyrelog.setUser(account.id);
  Lyrelog.info('signed_in', category: 'auth');
}

Future<void> choose(bool allowed) async {
  final prefs = await SharedPreferences.getInstance();
  await prefs.setString('diagnostics', allowed ? 'granted' : 'denied');
  Lyrelog.setConsent(allowed ? Consent.granted : Consent.denied);
}

Vider la file et arrêter

Le passage en arrière-plan envoie déjà : sur iOS dans une tâche d'arrière-plan, sur Android quand l'Activity de l'app s'arrête. Vous en aurez donc rarement besoin.

await Lyrelog.flush(); // write everything to disk and send, waiting up to 5 seconds
await Lyrelog.stop();  // send what's queued (up to 2 seconds), then stop

flush renvoie true quand elle a terminé à temps (timeout: change le délai d'attente), et respecte un Retry-After demandé par le serveur : elle n'envoie pas plus tôt. Après stop, start peut être rappelée.

En développement et dans les tests

Dans les tests de widgets et les tests unitaires, n'appelez pas Lyrelog.start : tout ce qui est journalisé avant start est ignoré, et le reste de votre code s'exécute sans changement. Sur une plateforme que le plugin ne prend pas en charge (web, desktop), les appels sont sans effet et ne lèvent jamais d'exception.

mirrorToConsole: true affiche aussi chaque événement dans le log natif pendant que vous travaillez : la console de Xcode sur iOS, logcat (tag Lyrelog) sur Android.

Les builds de debug envoient l'environnement development. Pour envoyer vers un endpoint qui tourne sur votre ordinateur :

  • Simulateur iOS : utilisez http://127.0.0.1 et son port. Le simulateur partage le réseau de votre ordinateur, et aucune exception App Transport Security n'est nécessaire pour cela.
  • Émulateur Android : utilisez http://10.0.2.2 et son port (10.0.2.2 est votre ordinateur, vu depuis l'émulateur), dans le build de debug uniquement :
    • Autorisez le http simple vers 10.0.2.2. Android le bloque sauf si l'app l'autorise : ajoutez au build de debug (android/app/src/debug) une network security config qui permet le trafic en clair pour cette seule adresse.
    • Sur Android 17, une app qui cible l'API 37 a aussi besoin de ACCESS_LOCAL_NETWORK pour joindre une adresse privée comme 10.0.2.2 ; sans elle, la connexion expire simplement. Déclarez la permission dans le manifeste de debug (android/app/src/debug/AndroidManifest.xml) et accordez-la : adb shell pm grant <your.app> android.permission.ACCESS_LOCAL_NETWORK.

Gardez la clé hors de vos sources avec --dart-define-from-file, par exemple flutter run --dart-define-from-file=lyrelog.local.json et String.fromEnvironment('LYRELOG_KEY'), avec ce fichier ignoré par git.

Cela ne sert qu'au développement local. L'ingestion hébergée est une adresse https publique et n'a besoin de rien de tout cela.

Événements vérifiés

Un événement vérifié est un événement qui n'a pas pu être envoyé par quelqu'un ayant extrait la clé d'ingestion publique d'une app ou d'une page web. Ce que cela prouve, et ce que cela ne prouve pas, est expliqué dans Événements vérifiés.

Les SDK natifs vérifient l'app sur les vrais appareils (attest, activé par défaut), et rien ne change dans votre code Dart. Configurez chaque plateforme sur laquelle l'app est distribuée :

  • iOS, avec App Attest d'Apple (verified_by vaut app_attest) :
    • Ajoutez la capability App Attest à la target Runner dans Xcode (Signing & Capabilities), c'est-à-dire l'entitlement com.apple.developer.devicecheck.appattest-environment. Réglez-le sur production pour les builds App Store et TestFlight ; sans cela, Apple utilise l'environnement de développement.
    • Ajoutez votre App ID, c'est-à-dire le Team ID, un point et le bundle id (ABCDE12345.com.example.app), dans Project settings, sous Verified events from your Apple apps.
  • Android, avec Key Attestation (verified_by vaut key_attestation) : dans Project settings, sous Verified events from your Android apps, ajoutez votre package et l'empreinte SHA-256 de chaque certificat qui signe des builds envoyant des événements : la clé de signature d'app de Play (Play Console, Test and release, App integrity) et, pour les builds que vous signez vous-même, celle qu'affiche ./gradlew signingReport (à lancer dans le dossier android de votre app).

Pour le désactiver sur les deux :

Lyrelog.start(const LyrelogConfiguration(apiKey: 'lyr_ing_...', attest: false));

L'envoi ne l'attend jamais : tant que l'app n'a pas de token, et chaque fois que quelque chose échoue, les événements sont envoyés non vérifiés. Tant qu'une plateforme n'est pas configurée dans le projet, le SDK cesse d'essayer pour ce lancement.

  • Le simulateur iOS et les émulateurs Android ne sont jamais vérifiés.
  • Un appareil que le serveur refuse (un téléphone rooté, un bootloader déverrouillé, un certificat que le projet ne liste pas) envoie des événements non vérifiés ; Android réessaie un jour plus tard.
  • Refuser le consentement supprime l'enregistrement de la clé attestée sur les deux plateformes.

Avant de faire accepter au projet uniquement les événements vérifiés pour ios ou android, vérifiez dans l'explorer que les événements de vos vrais utilisateurs arrivent vérifiés : les événements des anciennes versions, des simulateurs, des émulateurs et des appareils refusés seraient retenus avec un 425. Ne mettez jamais une clé serveur (lyr_srv_...) dans une app : tout ce qui est livré dans une app peut être lu.

Pour vérifier, ouvrez l'explorer : un événement ouvert l'indique sous Context, sur sa ligne Sender : Verified, App Attest, Verified, Key Attestation ou Not verified, public key.

Configuration

OptionPar défautSignification
apiKeyobligatoireLa clé d'ingestion du projet
endpointhttps://ingest.lyrelog.comL'URL de base ; un chemin /v1/... collé est retiré. https uniquement, http seulement pour localhost et le 10.0.2.2 de l'émulateur Android
consentConsent.grantedpending, granted ou denied
minimumLevelLogLevel.debugLes événements en dessous sont écartés avant d'atteindre la file de l'appareil
flushInterval15 sLa fréquence d'exécution de l'uploader au premier plan
maxBatchBytes512 KiBUn lot se ferme à la première limite atteinte (maintenu sous 4 MiB)
maxBatchEvents500Au plus 2 000
maxDiskBytes20 MBPlafond de la file sur disque, les plus anciens partent en premier
maxEventAge7 joursLes événements en file plus anciens sont abandonnés
sessionTimeout30 minLe temps d'inactivité qui ouvre une nouvelle session
environmentdétectéN'importe quel nom valide, ou null
platforml'OSN'importe quel nom valide, ou null
redactedKeysnull : defaultRedactedKeysLes noms de clés à masquer ; votre liste remplace celle par défaut, une liste vide désactive le masquage
captureErrorstrueRemonte les erreurs Dart que personne n'a interceptées
captureNativeCrashestrueiOS : plantages, blocages et rapports de surconsommation MetricKit. Android : exceptions JVM non interceptées. Envoyés au lancement suivant
attachScreentrueMarque les événements avec l'écran en cours
attesttrueVérifie les événements avec App Attest ou Key Attestation une fois le projet configuré
mirrorToConsolefalseAffiche aussi chaque événement dans le log natif (console de Xcode, logcat)
pauseUploadsInLowPowerModetrueiOS uniquement : les envois périodiques se mettent en pause ; le passage en arrière-plan envoie quand même

Livraison et limites

La livraison est celle du SDK natif, la même que dans une app Swift ou Kotlin :

iOSAndroid
Ne bloque jamaisUn appel transmet l'événement au SDK natif et rend la main ; un unique writer en arrière-plan l'écrit sur disque et n'attend jamais le réseau.Pareil.
Résiste aux arrêts forcés et au hors-ligneUne file dans Library/Caches, plafonnée à 20 MB et 7 jours. Le système peut purger Caches quand l'appareil manque d'espace, et les événements en attente partent avec.Une file dans noBackupFilesDir/lyrelog, plafonnée à 20 MB et 7 jours, jamais incluse dans une sauvegarde : un téléphone restauré ne renvoie donc pas les événements d'un autre appareil.
Quand il envoieToutes les 15 s au premier plan (en pause en mode économie d'énergie), et quand l'app passe en arrière-plan, dans une tâche d'arrière-plan.Toutes les 15 s tant que l'Activity de l'app est démarrée, et quand elle passe en arrière-plan. En arrière-plan, rien ne tourne sur minuteur : ce qui reste part au lancement suivant ou la prochaine fois que l'app revient au premier plan.
LotsJusqu'à 500 événements ou 512 KiB par requête, compressés en gzip. Un événement de plus de 1 MiB une fois encodé est abandonné et compté.Pareil.
Nouvelles tentatives1 s, doublé jusqu'à 5 min, avec full jitter, en respectant Retry-After. Tout autre 4xx abandonne le lot, un 3xx (une redirection, jamais suivie) l'abandonne aussi, et une clé révoquée (401, 403) arrête les envois jusqu'au lancement suivant et conserve les événements. Un lot que le serveur continue de refuser alors que d'autres passent est remis en fin de file, puis abandonné.Pareil.
Quota mensuelQuand une organisation Free a épuisé les événements de son mois, le serveur répond 429. Les événements restent dans la file sur disque et partent dès que le serveur les accepte de nouveau, dans les limites de 20 MB et de 7 jours. Un avertissement dans le log unifié (sous-système com.lyrelog.sdk).Pareil, avec l'avertissement dans logcat (tag Lyrelog).
Les pertes sont visiblesLes événements perdus à cause des plafonds deviennent un avertissement lyrelog_events_dropped (domaine lyrelog) avec leur nombre.Pareil.
Ses propres problèmesUn endpoint incorrect, une clé refusée ou des lignes rejetées sont signalés une fois par lancement dans le log unifié, sous-système com.lyrelog.sdk, au niveau debug.Pareil dans logcat, tag Lyrelog, au niveau debug.
ContexteIdentifiant de l'app, version, build, OS, modèle d'appareil (iPhone18,1), locale, plateforme ios, id de session (nouveau après 30 min d'inactivité) et id d'installation. sdk vaut lyrelog-flutter/0.1.0 lyrelog-swift/0.1.0.Identifiant de l'app (le nom du package), version name, version code, la version d'Android, l'appareil (Google Pixel 9), locale, plateforme android, id de session et id d'installation. sdk vaut lyrelog-flutter/0.1.0 lyrelog-android/0.1.0.
SecretsLes valeurs sous des clés dont le nom est ou se termine par authorization, cookie, password, token, secret, apikey et le reste de la liste commune deviennent "[redacted]", à toute profondeur, avant toute troncature.Pareil.
LimitesLes chaînes longues sont coupées sur une limite de caractère, les attributs en trop comptés dans lyrelog_dropped_attrs, les payloads de plus de 64 KiB résumés en {"lyrelog_truncated": true, "bytes": N, "preview": "..."}.Pareil.

Modifiez la liste de masquage avec redactedKeys : votre liste remplace celle par défaut, et une liste vide désactive le masquage. Pour la compléter :

Lyrelog.start(const LyrelogConfiguration(
  apiKey: 'lyr_ing_...',
  redactedKeys: [...LyrelogConfiguration.defaultRedactedKeys, 'pin'],
));

Confidentialité sur l'App Store et sécurité des données sur Play

Le manifeste de confidentialité du SDK Swift (PrivacyInfo.xcprivacy) est livré dans l'app, et Xcode le fusionne dans le rapport de confidentialité de l'app, comme sur la page Swift.

Pour l'étiquette de confidentialité de l'App Store, déclarez ce que votre app envoie via Lyrelog :

  • Diagnostics : Crash Data, Performance Data, Other Diagnostic Data (App Functionality).
  • Identifiers > Device ID : l'id d'installation, un UUID aléatoire qui n'est pas l'identifiant publicitaire, n'est pas sauvegardé et est supprimé en cas de refus (App Functionality). Non lié à la personne, sauf si vous appelez aussi setUser.
  • Identifiers > User ID, lié à la personne : seulement si vous appelez setUser.
  • Usage Data > Product Interaction : si vous journalisez les écrans (screen_viewed) ou les appuis.

Pour le formulaire de sécurité des données de la Play Console :

  • App info and performance : Crash logs, Diagnostics (App functionality, et Analytics si vous les utilisez ainsi). Collectées, non partagées.
  • Device or other IDs : l'id d'installation, comme ci-dessus.
  • App activity > App interactions : si vous journalisez les écrans ou les appuis.

Dans les deux cas, tout ce que vos attrs ou votre payload contiennent d'autre (e-mails, achats...) va dans sa propre catégorie. Les données sont chiffrées en transit (https). Le serveur ajoute le pays de l'adresse d'envoi ; l'adresse elle-même n'est pas conservée.