Flutter
Logs estructurados desde tu app de Flutter en iOS y Android, sobre los SDK nativos de Lyrelog.
El SDK de Flutter es el paquete de Dart lyrelog, un plugin para iOS 16 y Android 7.0 (API 24) o
posteriores, hecho con Flutter 3.50. Es una capa ligera de Dart sobre los SDK nativos, el
SDK de Swift en iOS y el SDK de Android en Android, así que la cola
en disco, los crashes nativos, el envío en segundo plano, las sesiones, el consentimiento y los
eventos verificados funcionan igual que en ellos. Además, registra los errores de Dart que nadie
captura y pone nombre a las pantallas a partir de tu navigator.
Versión preliminar interna: este paquete aún no está publicado. Hasta que lo esté,
flutter pub add lyrelog no encuentra nada: no está en pub.dev, y el repositorio es privado y
todavía no tiene ninguna release.
Instalación
flutter pub add lyrelogO en pubspec.yaml:
dependencies:
lyrelog: ^0.1.0Configuración en iOS
- El plugin es un paquete Swift, así que tu app lo compila con Swift Package Manager, que Flutter usa por defecto. No hay versión para CocoaPods.
- Pon el mínimo de la app en iOS 16: en Xcode, el target Runner, General, Minimum
Deployments (
IPHONEOS_DEPLOYMENT_TARGET = 16.0). El valor por defecto de Flutter es más bajo, y la build se detiene con un mensaje que lo indica.
Configuración en Android
- Los valores por defecto de Flutter funcionan: compileSdk 36 y Kotlin 2.2 o posterior.
minSdkpuede quedarse en 24.
La biblioteca añade el permiso INTERNET al manifest de tu app.
Primeros pasos
Arranca el SDK una sola vez y lo antes posible: en main, antes de runApp. Una segunda
llamada mientras está en marcha se ignora. start llama por sí mismo a
WidgetsFlutterBinding.ensureInitialized(), así que puede ir lo primero, y nada tiene que
esperarlo: lo que registres después de start llega al SDK nativo después de él. Los eventos
registrados antes de start se ignoran, pero setUser y setConsent llamados antes de start
se guardan y se aplican cuando se ejecuta.
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());
}Los eventos van a https://ingest.lyrelog.com. Pasa endpoint solo para enviarlos a otro sitio.
Es la URL base (si pegas una ruta .../v1/events:batch, se elimina) y tiene que ser https;
http sin cifrar solo funciona con localhost, 127.0.0.1 o ::1, y en el emulador de Android
con 10.0.2.2 (consulta En desarrollo y en tests). Con cualquier
otro endpoint no se envía nada y los eventos se quedan en el dispositivo.
Registrar eventos
Una función por nivel: trace, debug, info, notice, warning, error, critical, o
log(level, message, ...) con un LogLevel.
Lyrelog.info('checkout_done', attrs: {'items': 3, 'latency_ms': ms});
Lyrelog.error('payment_declined', category: 'checkout',
attrs: {'code': 51}, payload: {'response': raw});Los atributos son un Map<String, Object?>: cadenas, números, booleanos, null, listas y mapas
anidados de hasta 4 niveles. Un DateTime se envía como texto ISO 8601, un Duration en
milisegundos, un enum como su nombre, y cualquier otra cosa como su toString(). El payload es
cualquier valor de esos tipos, para el detalle que solo lees al abrir un evento.
Loggers por área
Un logger pone su category en cada evento, como una etiqueta de log. Tiene todos los niveles,
además de log y captureError. Es barato de crear y de conservar, y registra en el SDK que esté
en marcha cuando se le llama.
final sync = Lyrelog.logger('sync');
sync.warning('sync_conflict', attrs: {'records': 2});Usuarios
Lyrelog.setUser(account.id); // attached to every following event
Lyrelog.setUser(null); // on sign-outawait Lyrelog.sessionId() da el id de la sesión actual, por ejemplo para mostrarlo en una
pantalla de soporte.
El id de usuario no se guarda entre arranques: vuelve a llamar a setUser en cada arranque, en
cuanto sepas quién es la persona.
Pantallas
Indica dónde está la persona. Lyrelog registra screen_viewed (área navigation) con la pantalla
anterior y los segundos que pasó en ella, y etiqueta cada evento siguiente con un atributo
screen.
Añade LyrelogNavigatorObserver al navigator de tu app, y cada page route que pasa a primer plano
es una pantalla, con el nombre de su ruta:
MaterialApp(
navigatorObservers: [LyrelogNavigatorObserver()],
routes: {
'/': (_) => const HomePage(),
'/settings': (_) => const SettingsPage(),
},
)Funciona con cualquier Navigator, así que también con un router que acepte observers (con
go_router, GoRouter(observers: [LyrelogNavigatorObserver()], ...)). Volver a una página la
registra otra vez, porque vuelve a ser la pantalla actual. Los diálogos, los bottom sheets y los
menús no cambian la pantalla, y las rutas sin nombre se omiten. Puedes cambiar las dos cosas:
LyrelogNavigatorObserver(
nameExtractor: (settings) => settings.name?.replaceFirst('/', ''), // null or '' skips the route
routeFilter: (route) => route is PageRoute, // which routes are screens
)O llámalo tú:
Lyrelog.screen('Settings');El evento lleva screen, previous_screen y seconds_on_previous. Llamar a screen otra vez con
el mismo nombre no registra nada. screen acepta attrs adicionales para el evento
screen_viewed. Desactiva el etiquetado con attachScreen: false.
Errores que capturas
try {
await store.purchase(product);
} catch (e, s) {
Lyrelog.captureError(e, stackTrace: s, category: 'store');
}Envía el evento exception que envían todos los SDK: nivel error, los atributos error_type (el
tipo en tiempo de ejecución) y error_message (su toString()), y un payload con la descripción y
hasta 60 frames del stack. Sin stackTrace, los frames son el stack propio de un Error, si lo
tiene. attrs añade los tuyos; level cambia el nivel. Cada logger también tiene captureError.
Errores y crashes
Errores de Dart que nadie captura
start los registra por su cuenta (captureErrors, activado por defecto), como eventos
exception con handled: false y un mechanism que indica dónde los entregó Flutter:
mechanism | De dónde | El payload también lleva |
|---|---|---|
flutter_error | FlutterError.onError: errores al construir, maquetar o pintar widgets, y en callbacks de gestos | library (widgets library) y context (building MyWidget) |
platform_dispatcher | PlatformDispatcher.instance.onError: errores en código asíncrono, en temporizadores y en futures que nadie esperó |
Los handlers que había antes siguen ejecutándose, después de los de Lyrelog, y
PlatformDispatcher.onError devuelve lo que devolvía el anterior (si no había ninguno, Flutter
sigue imprimiendo el error). Si configuras tus propios handlers, hazlo antes de start, o llama a
captureError desde ellos.
Se envían como máximo 10 por minuto, y el mismo error (su tipo, su mensaje y su frame superior) solo una vez cada 10 segundos, así que un error de layout que se repite en cada frame envía un solo evento. Los errores que Flutter marca como silenciosos, que tampoco notifica en las builds de release (una imagen que no se pudo cargar, por ejemplo), se dejan fuera.
Un error de Dart no cierra una app de Flutter, así que son eventos exception, nunca
app_crashed.
Si tu app se ejecuta en una zona propia, registra los errores de la zona del mismo modo:
runZonedGuarded(() => runApp(const MyApp()), (error, stack) {
Lyrelog.captureError(error, stackTrace: stack, handled: false, mechanism: 'zone');
});Crashes nativos
Los crashes de la propia app llegan de los SDK nativos (captureNativeCrashes, activado por
defecto). Se envían en el siguiente arranque, con la hora en que ocurrieron, en el área
diagnostics:
| Plataforma | Eventos | De dónde |
|---|---|---|
| iOS | app_crashed (critical), app_hung (error), cpu_overuse, disk_write_overuse, slow_launch (warnings) | MetricKit, como en la página de Swift |
| Android | app_crashed (critical) con handled: false y mechanism: uncaught_exception | Excepciones de la JVM no capturadas, como en la página de Android |
En Android, los crashes nativos (C o C++) y los ANR no se registran.
Builds ofuscadas
Con flutter build --obfuscate --split-debug-info=<dir>, los nombres de tipo de error_type y de
los frames quedan ofuscados. Guarda los símbolos que escribe la build y ejecuta
flutter symbolize con ellos sobre los frames para poder leerlos.
Entornos y plataforma
El SDK nativo elige el entorno al arrancar:
- iOS:
developmentpara una build de debug, cualquier build en el simulador o una build con un provisioning profile incrustado (firma de desarrollo y ad hoc);testflightpara una build de TestFlight;productionen cualquier otro caso. Después, la respuesta de StoreKit, como en la página de Swift. - Android:
developmentcuando la app es depurable (todas las builds de debug) yproductionen cualquier otro caso.
Tus propias builds de flutter run envían development, mientras que el panel se abre en
production: elige development en la barra superior para verlas.
La plataforma es el sistema operativo, ios o android, así que un mismo proyecto recoge las dos
y el panel puede filtrar por cada una. Puedes sobrescribir cualquiera de los dos en la
configuración:
LyrelogConfiguration(
apiKey: key,
environment: isInternalTester ? 'internal' : null, // null = detected
platform: null,
)Vale cualquier nombre: letras minúsculas, dígitos, - y _, hasta 32. Cualquier otro texto se
convierte en un nombre válido (Staging EU pasa a ser staging-eu).
Consentimiento
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 recordingConsent.pending guarda los eventos en el dispositivo sin enviarlos. No se sube nada si no se ha
concedido el consentimiento, tampoco lo que dejó un arranque anterior. Arrancar con
Consent.denied borra lo que quede en la cola de un arranque anterior y el id de instalación, y no
registra nada. Un setConsent antes de start prevalece sobre el consent de la configuración.
El consentimiento no se guarda entre arranques: guarda tú la elección de la persona y pásala a
start cada vez.
Una app completa
Arranca con el consentimiento guardado, asigna la persona cuando inicia sesión y pon nombre a las pantallas a partir del 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);
}Vaciar la cola y detener
Pasar a segundo plano ya envía: en iOS, dentro de una background task; en Android, cuando se detiene la Activity de la app. Así que rara vez te hará falta.
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 stopflush devuelve true cuando termina a tiempo (timeout: cambia la espera), y respeta el
Retry-After que haya pedido el servidor: no envía antes. Después de stop se puede volver a
llamar a start.
En desarrollo y en tests
En los tests de widgets y unitarios, no llames a Lyrelog.start: todo lo que se registra antes de
start se ignora, así que el resto de tu código se ejecuta sin cambios. En una plataforma que el
plugin no admite (web, escritorio), ninguna llamada hace nada ni lanza excepciones.
Con mirrorToConsole: true, además, cada evento se imprime en el log nativo mientras trabajas: la
consola de Xcode en iOS y logcat (etiqueta Lyrelog) en Android.
Las builds de debug envían el entorno development. Para enviar a un endpoint que corre en tu
ordenador:
- Simulador de iOS: usa
http://127.0.0.1y su puerto. El simulador comparte la red de tu ordenador, y no hace falta ninguna excepción de App Transport Security para ello. - Emulador de Android: usa
http://10.0.2.2y su puerto (10.0.2.2es tu ordenador visto desde el emulador), solo en la build de debug:- Permite http sin cifrar hacia
10.0.2.2. Android lo bloquea salvo que la app lo permita: añade a la build de debug (android/app/src/debug) una network security config que permita cleartext para esa única dirección. - En Android 17, una app con target API 37 también necesita
ACCESS_LOCAL_NETWORKpara llegar a una dirección privada como10.0.2.2; sin él, la conexión simplemente agota el tiempo de espera. Declara el permiso en el manifest de debug (android/app/src/debug/AndroidManifest.xml) y concédelo:adb shell pm grant <your.app> android.permission.ACCESS_LOCAL_NETWORK.
- Permite http sin cifrar hacia
Deja la clave fuera de tu código fuente con --dart-define-from-file, por ejemplo
flutter run --dart-define-from-file=lyrelog.local.json y
String.fromEnvironment('LYRELOG_KEY'), con ese archivo ignorado por git.
Esto es solo para desarrollo local. La ingesta alojada es una dirección https pública y no
necesita nada de esto.
Eventos verificados
Un evento verificado es uno que no puede haber enviado alguien que copió la clave de ingesta pública de una app o de una página web. Qué demuestra eso, y qué no, está en Eventos verificados.
Los SDK nativos verifican la app en dispositivos reales (attest, activado por defecto), y en tu
código Dart no cambia nada. Configura cada plataforma en la que se publica la app:
- iOS, con App Attest de Apple (
verified_byesapp_attest):- Añade la capability App Attest al target Runner en Xcode (Signing & Capabilities), el
entitlement
com.apple.developer.devicecheck.appattest-environment. Ponlo aproductionpara las builds de App Store y TestFlight; sin él, Apple usa el entorno de desarrollo. - Añade tu App ID, es decir, el Team ID, un punto y el bundle id
(
ABCDE12345.com.example.app), en Project settings, en Verified events from your Apple apps.
- Añade la capability App Attest al target Runner en Xcode (Signing & Capabilities), el
entitlement
- Android, con Key Attestation
(
verified_byeskey_attestation): en Project settings, en Verified events from your Android apps, añade tu paquete y la huella SHA-256 de cada certificado que firme builds que envían eventos: la clave de firma de apps de Play (Play Console, Test and release, App integrity) y, para las builds que firmas tú, la que muestra./gradlew signingReport(ejecútalo en la carpetaandroidde tu app).
Para desactivarlo en las dos:
Lyrelog.start(const LyrelogConfiguration(apiKey: 'lyr_ing_...', attest: false));El envío nunca espera a la atestación: hasta que la app tiene un token, y cada vez que algo falla, los eventos se envían sin verificar. Mientras una plataforma no esté configurada en el proyecto, el SDK deja de intentarlo durante ese arranque.
- El simulador de iOS y los emuladores de Android nunca verifican.
- Un dispositivo que el servidor rechaza (un teléfono rooteado, un bootloader desbloqueado, un certificado que el proyecto no tiene en su lista) envía eventos sin verificar; Android vuelve a intentarlo un día después.
- Denegar el consentimiento borra el registro de la clave atestada en las dos plataformas.
Antes de hacer que el proyecto acepte solo eventos verificados de ios o android, comprueba en
el explorador que los eventos de tus usuarios reales llegan verificados: los eventos de versiones
antiguas, simuladores, emuladores y dispositivos rechazados se quedarían retenidos con un 425.
Nunca pongas una clave de servidor (lyr_srv_...) en una app: cualquier cosa que vaya en una app
se puede leer.
Para comprobarlo, abre el explorador: un evento abierto lo indica en Context, en su línea Sender: Verified, App Attest, Verified, Key Attestation o Not verified, public key.
Configuración
| Opción | Por defecto | Significado |
|---|---|---|
apiKey | obligatoria | La clave de ingesta del proyecto |
endpoint | https://ingest.lyrelog.com | La URL base; si pegas una ruta /v1/..., se elimina. Solo https; http solo para localhost y el 10.0.2.2 del emulador de Android |
consent | Consent.granted | pending, granted o denied |
minimumLevel | LogLevel.debug | Los eventos por debajo se descartan antes de llegar a la cola del dispositivo |
flushInterval | 15 s | Cada cuánto se ejecuta el envío en primer plano |
maxBatchBytes | 512 KiB | Un lote se cierra en el primer límite que se alcance (se mantiene dentro de 4 MiB) |
maxBatchEvents | 500 | Como máximo 2.000 |
maxDiskBytes | 20 MB | Tope de la cola en disco; se descartan primero los más antiguos |
maxEventAge | 7 días | Los eventos en cola más antiguos se descartan |
sessionTimeout | 30 min | Tiempo de inactividad que inicia una sesión nueva |
environment | detectado | Cualquier nombre válido, o null |
platform | el sistema operativo | Cualquier nombre válido, o null |
redactedKeys | null: defaultRedactedKeys | Nombres de clave cuyos valores se ocultan; tu lista sustituye a la predeterminada, y una lista vacía desactiva la ocultación |
captureErrors | true | Registra los errores de Dart que nadie capturó |
captureNativeCrashes | true | iOS: crashes, bloqueos e informes de uso excesivo de MetricKit. Android: excepciones de la JVM no capturadas. Se envían en el siguiente arranque |
attachScreen | true | Etiqueta los eventos con la pantalla actual |
attest | true | Verifica los eventos con App Attest o Key Attestation cuando el proyecto está configurado |
mirrorToConsole | false | Imprime además cada evento en el log nativo (la consola de Xcode, logcat) |
pauseUploadsInLowPowerMode | true | Solo iOS: los envíos periódicos se pausan; pasar a segundo plano sigue enviando |
Entrega y límites
La entrega es la del SDK nativo, la misma que en una app de Swift o Kotlin:
| iOS | Android | |
|---|---|---|
| Nunca bloquea | Una llamada pasa el evento al SDK nativo y vuelve; un único proceso de escritura en segundo plano lo pone en disco y nunca espera a la red. | Igual. |
| Sobrevive a cierres forzados y a la falta de conexión | Una cola en Library/Caches, con un tope de 20 MB y 7 días. El sistema puede vaciar Caches cuando el dispositivo se queda sin espacio, y los eventos en espera se van con ello. | Una cola en noBackupFilesDir/lyrelog, con un tope de 20 MB y 7 días, que nunca entra en una copia de seguridad, así que un teléfono restaurado no reenvía los eventos de otro dispositivo. |
| Cuándo envía | Cada 15 s en primer plano (en pausa en el modo de bajo consumo), y cuando la app pasa a segundo plano, dentro de una background task. | Cada 15 s mientras la Activity de la app está iniciada, y cuando pasa a segundo plano. En segundo plano no se ejecuta nada con temporizador: lo que queda sale en el siguiente arranque o la próxima vez que la app pasa al frente. |
| Lotes | Hasta 500 eventos o 512 KiB por petición, con gzip. Un evento de más de 1 MiB una vez codificado se descarta y se cuenta. | Igual. |
| Reintentos | 1 s, doblando hasta 5 min, con full jitter y respetando Retry-After. Cualquier otro 4xx descarta el lote, un 3xx (una redirección, que nunca se sigue) también lo descarta, y una clave revocada (401, 403) detiene los envíos hasta el siguiente arranque y conserva los eventos. Un lote que el servidor sigue rechazando mientras otros pasan se manda al final de la cola y después se descarta. | Igual. |
| Cuota mensual | Cuando una organización Free ha gastado los eventos del mes, el servidor responde 429. Los eventos se quedan en la cola en disco y salen cuando el servidor vuelve a aceptarlos, dentro de los topes de 20 MB y 7 días. Un aviso en el unified log (subsistema com.lyrelog.sdk). | Igual, con el aviso en logcat (etiqueta Lyrelog). |
| Los descartes se ven | Los eventos perdidos por los topes se convierten en un aviso lyrelog_events_dropped (área lyrelog) con el número. | Igual. |
| Sus propios problemas | Un endpoint incorrecto, una clave rechazada o líneas rechazadas se registran una vez por arranque en el unified log, subsistema com.lyrelog.sdk, a nivel debug. | Igual, en logcat, etiqueta Lyrelog, a nivel debug. |
| Contexto | Id de la app, versión, build, sistema operativo, modelo de dispositivo (iPhone18,1), configuración regional, plataforma ios, id de sesión (nuevo tras 30 min de inactividad) e id de instalación. sdk es lyrelog-flutter/0.1.0 lyrelog-swift/0.1.0. | Id de la app (el nombre del paquete), version name, version code, la versión de Android, el dispositivo (Google Pixel 9), configuración regional, plataforma android, id de sesión e id de instalación. sdk es lyrelog-flutter/0.1.0 lyrelog-android/0.1.0. |
| Secretos | Los valores de las claves cuyo nombre es o termina en authorization, cookie, password, token, secret, apikey y el resto de la lista común pasan a ser "[redacted]", a cualquier profundidad, antes de recortar nada. | Igual. |
| Límites | Las cadenas largas se cortan sin partir ningún carácter, los atributos de más se cuentan en lyrelog_dropped_attrs y los payloads de más de 64 KiB se resumen como {"lyrelog_truncated": true, "bytes": N, "preview": "..."}. | Igual. |
Cambia la lista de ocultación con redactedKeys: tu lista sustituye a la predeterminada, y una
lista vacía desactiva la ocultación. Para ampliarla:
Lyrelog.start(const LyrelogConfiguration(
apiKey: 'lyr_ing_...',
redactedKeys: [...LyrelogConfiguration.defaultRedactedKeys, 'pin'],
));Privacidad en el App Store y seguridad de los datos en Play
El manifiesto de privacidad del SDK de Swift (PrivacyInfo.xcprivacy) va dentro de la app, y Xcode
lo combina en el informe de privacidad de la app, como en la
página de Swift.
Para la etiqueta de privacidad del App Store, declara lo que tu app envía a través de Lyrelog:
- Diagnostics: Crash Data, Performance Data, Other Diagnostic Data (App Functionality).
- Identifiers > Device ID: el id de instalación, un UUID aleatorio que no es el id de
publicidad, no entra en las copias de seguridad y se borra si se deniega el consentimiento (App
Functionality). No está vinculado a la persona salvo que también llames a
setUser. - Identifiers > User ID, vinculado a la persona: solo si llamas a
setUser. - Usage Data > Product Interaction: si registras pantallas (
screen_viewed) o toques.
Para el formulario de seguridad de los datos de Play Console:
- App info and performance: Crash logs, Diagnostics (App functionality, y Analytics si lo usas para eso). Recogidos, no compartidos.
- Device or other IDs: el id de instalación, como arriba.
- App activity > App interactions: si registras pantallas o toques.
En los dos, cualquier otra cosa que lleven tus attrs o tu payload (emails, compras...) va en su
propia categoría. Los datos van cifrados en tránsito (https). El servidor añade el país de la
dirección que envía; la propia dirección no se guarda.