Flutter
Logs estruturados do seu app Flutter no iOS e no Android, por cima dos SDKs nativos do Lyrelog.
O SDK de Flutter é o pacote Dart lyrelog, um plugin para iOS 16 e Android 7.0 (API 24) ou
posterior, feito com Flutter 3.50. Ele é uma camada fina de Dart por cima dos SDKs nativos, o
SDK de Swift no iOS e o SDK de Android no Android, então a fila
em disco, os crashes nativos, o envio em segundo plano, as sessões, o consentimento e os eventos
verificados funcionam como neles. Além disso, ele reporta os erros de Dart que ninguém capturou e
dá nome às telas a partir do seu navigator.
Prévia interna: este pacote ainda não foi publicado. Até lá, flutter pub add lyrelog não
encontra nada: ele não está no pub.dev, e o repositório é privado e ainda não tem nenhuma
release.
Instalação
flutter pub add lyrelogOu no pubspec.yaml:
dependencies:
lyrelog: ^0.1.0Configuração no iOS
- O plugin é um pacote Swift, então o seu app o compila com o Swift Package Manager, que o Flutter usa por padrão. Não existe versão para CocoaPods.
- Defina a versão mínima do app como iOS 16: no Xcode, no target Runner, em General,
Minimum Deployments (
IPHONEOS_DEPLOYMENT_TARGET = 16.0). O padrão do Flutter é mais baixo, e o build para com uma mensagem avisando disso.
Configuração no Android
- Os padrões do Flutter funcionam: compileSdk 36 e Kotlin 2.2 ou mais recente. O
minSdkpode ficar em 24.
A biblioteca adiciona a permissão INTERNET ao manifest do seu app.
Primeiros passos
Inicie uma única vez, o mais cedo possível: no main, antes do runApp. Uma segunda chamada
enquanto ele está rodando é ignorada. O próprio start chama
WidgetsFlutterBinding.ensureInitialized(), então ele pode vir primeiro, e nada precisa esperar
por ele: o que você registrar depois de start chega ao SDK nativo depois dele. Eventos
registrados antes de start são ignorados, mas setUser e setConsent chamados antes de
start são guardados e aplicados quando ele roda.
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());
}Os eventos vão para https://ingest.lyrelog.com. Passe endpoint só para enviá-los para outro
lugar. Ele é a URL base (um caminho .../v1/events:batch colado é removido) e precisa ser
https; http simples só funciona para localhost, 127.0.0.1 ou ::1 e, no emulador do
Android, para 10.0.2.2 (veja Em desenvolvimento e testes). Com
qualquer outro endpoint, nada é enviado e os eventos ficam no dispositivo.
Registrar eventos
Uma função por nível: trace, debug, info, notice, warning, error, critical, ou
log(level, message, ...) com um LogLevel.
Lyrelog.info('checkout_done', attrs: {'items': 3, 'latency_ms': ms});
Lyrelog.error('payment_declined', category: 'checkout',
attrs: {'code': 51}, payload: {'response': raw});Os atributos são um Map<String, Object?>: strings, números, booleanos, null, listas e maps
aninhados em até 4 níveis. Um DateTime é enviado como texto ISO 8601, uma Duration em
milissegundos, um enum pelo nome, e qualquer outra coisa pelo seu toString(). O payload é
qualquer valor desses tipos, para o detalhe que você só lê quando abre um evento.
Loggers para cada área
Um logger marca a sua category em todo evento, como uma tag de log. Ele tem todos os níveis,
além de log e captureError. É barato de criar e de manter, e registra no SDK que estiver
rodando no momento da chamada.
final sync = Lyrelog.logger('sync');
sync.warning('sync_conflict', attrs: {'records': 2});Usuários
Lyrelog.setUser(account.id); // attached to every following event
Lyrelog.setUser(null); // on sign-outawait Lyrelog.sessionId() traz o id da sessão atual, por exemplo para mostrar em uma tela de
suporte.
O id do usuário não é salvo entre uma inicialização e outra: chame setUser de novo a cada
inicialização, assim que souber quem é a pessoa.
Telas
Diga onde a pessoa está. O Lyrelog registra screen_viewed (área navigation) com a tela
anterior e os segundos passados nela, e marca todo evento seguinte com um atributo screen.
Adicione o LyrelogNavigatorObserver ao navigator do seu app, e toda rota de página que chegar
ao topo vira uma tela, com o nome da rota:
MaterialApp(
navigatorObservers: [LyrelogNavigatorObserver()],
routes: {
'/': (_) => const HomePage(),
'/settings': (_) => const SettingsPage(),
},
)Ele funciona com qualquer Navigator, então também com um router que aceite observers (com o
go_router, GoRouter(observers: [LyrelogNavigatorObserver()], ...)). Voltar para uma página a
registra de novo, já que ela volta a ser a tela atual. Diálogos, bottom sheets e menus não mudam
a tela, e rotas sem nome são ignoradas. Para mudar qualquer um dos dois:
LyrelogNavigatorObserver(
nameExtractor: (settings) => settings.name?.replaceFirst('/', ''), // null or '' skips the route
routeFilter: (route) => route is PageRoute, // which routes are screens
)Ou chame você mesmo:
Lyrelog.screen('Settings');O evento traz screen, previous_screen e seconds_on_previous. Chamar screen de novo com o
mesmo nome não registra nada. screen aceita attrs extras para o evento screen_viewed.
Desative a marcação com attachScreen: false.
Erros que você captura
try {
await store.purchase(product);
} catch (e, s) {
Lyrelog.captureError(e, stackTrace: s, category: 'store');
}Capturar um erro envia o evento exception que todo SDK envia: nível error, os atributos error_type (o
tipo em tempo de execução) e error_message (o seu toString()), e um payload com a descrição e
até 60 frames da stack. Sem um stackTrace, os frames são a stack do próprio Error, se ele
tiver uma. attrs acrescenta os seus; level muda o nível. Cada logger também tem
captureError.
Erros e crashes
Erros de Dart que ninguém captura
O start os reporta sozinho (captureErrors, ativado por padrão), como eventos exception com
handled: false e um mechanism que diz onde o Flutter os entregou:
mechanism | Origem | O payload também tem |
|---|---|---|
flutter_error | FlutterError.onError: erros ao construir, fazer o layout ou pintar widgets, e em callbacks de gestos | library (widgets library) e context (building MyWidget) |
platform_dispatcher | PlatformDispatcher.instance.onError: erros em código assíncrono, timers e futures que ninguém aguardou |
Os handlers que já existiam continuam rodando, depois dos do Lyrelog, e o
PlatformDispatcher.onError responde o que o anterior respondia (sem um anterior, o Flutter
continua imprimindo o erro). Se você define handlers próprios, defina-os antes de start, ou
chame captureError a partir deles.
No máximo 10 desses erros são enviados por minuto, e o mesmo erro (o tipo, a mensagem e o frame do topo) só uma vez a cada 10 segundos, então um erro de layout que se repete a cada frame envia um único evento. Erros que o Flutter marca como silenciosos, e que ele também não reporta em builds de release (uma imagem que falhou ao carregar, por exemplo), ficam de fora.
Um erro de Dart não encerra um app Flutter, então esses são eventos exception, nunca
app_crashed.
Se o seu app roda em uma zone própria, reporte os erros da zone do mesmo jeito:
runZonedGuarded(() => runApp(const MyApp()), (error, stack) {
Lyrelog.captureError(error, stackTrace: stack, handled: false, mechanism: 'zone');
});Crashes nativos
Os crashes do próprio app vêm dos SDKs nativos (captureNativeCrashes, ativado por padrão). Eles
são enviados na próxima inicialização, com a hora em que aconteceram, na área diagnostics:
| Plataforma | Eventos | Origem |
|---|---|---|
| iOS | app_crashed (critical), app_hung (error), cpu_overuse, disk_write_overuse, slow_launch (warnings) | MetricKit, como na página de Swift |
| Android | app_crashed (critical) com handled: false e mechanism: uncaught_exception | Exceções da JVM não capturadas, como na página de Android |
No Android, crashes nativos (C ou C++) e ANRs não são reportados.
Builds ofuscados
Com flutter build --obfuscate --split-debug-info=<dir>, os nomes de tipo em error_type e nos
frames ficam ofuscados. Guarde os símbolos que o build gera e rode flutter symbolize com eles
sobre os frames para conseguir lê-los.
Ambientes e plataforma
O SDK nativo escolhe o ambiente ao iniciar:
- iOS:
developmentpara um build de debug, qualquer build no simulador ou um build com um provisioning profile embutido (assinatura de development e ad hoc);testflightpara um build do TestFlight;productionnos outros casos. Depois, a resposta do StoreKit, como na página de Swift. - Android:
developmentquando o app é depurável (todo build de debug),productionnos outros casos.
Os seus próprios builds com flutter run enviam development, enquanto o painel abre em
production: escolha development na barra superior para vê-los.
A plataforma é o sistema operacional, ios ou android, então um mesmo projeto abriga os dois e
o painel pode filtrar por cada um. Sobrescreva qualquer um dos dois na configuração:
LyrelogConfiguration(
apiKey: key,
environment: isInternalTester ? 'internal' : null, // null = detected
platform: null,
)Qualquer nome serve: letras minúsculas, dígitos, - e _, até 32. Outros textos são
convertidos em um nome válido (Staging EU vira staging-eu).
Consentimento
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 mantém os eventos no dispositivo sem enviá-los. Nada é enviado a menos que o
consentimento seja dado, inclusive o que uma inicialização anterior deixou. Iniciar com
Consent.denied apaga tudo o que ainda estiver na fila de uma inicialização anterior e o id da
instalação, e não registra nada. Um setConsent antes de start prevalece sobre o consent da
configuração.
O consentimento não é salvo entre uma inicialização e outra: guarde você mesmo a escolha da
pessoa e passe-a para start a cada vez.
Um app completo
Inicie com o consentimento guardado, defina a pessoa quando ela entrar e dê nome às telas a partir do 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);
}Esvaziar a fila e parar
Ir para segundo plano já esvazia a fila: no iOS dentro de uma background task, no Android quando a Activity do app para. Então você raramente vai precisar fazer isso.
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 retorna true quando termina a tempo (timeout: muda a espera), e respeita um
Retry-After pedido pelo servidor: não envia antes disso. Depois de stop, start pode ser
chamado de novo.
Em desenvolvimento e testes
Em testes de widget e unitários, não chame Lyrelog.start: tudo o que for registrado antes de
start é ignorado, então o resto do seu código roda sem mudanças. Em uma plataforma que o plugin
não suporta (web, desktop), as chamadas não fazem nada e nunca lançam exceção.
mirrorToConsole: true também imprime cada evento no log nativo enquanto você trabalha: o
console do Xcode no iOS, o logcat (tag Lyrelog) no Android.
Builds de debug enviam o ambiente development. Para enviar para um endpoint rodando no seu
computador:
- Simulador do iOS: use
http://127.0.0.1e a porta dele. O simulador compartilha a rede do seu computador, e não é preciso nenhuma exceção de App Transport Security para isso. - Emulador do Android: use
http://10.0.2.2e a porta dele (10.0.2.2é o seu computador, visto pelo emulador), só no build de debug:- Permita http simples para
10.0.2.2. O Android o bloqueia, a menos que o app permita: adicione ao build de debug (android/app/src/debug) uma network security config que libere cleartext para esse endereço específico. - No Android 17, um app com target na API 37 também precisa de
ACCESS_LOCAL_NETWORKpara acessar um endereço privado como10.0.2.2; sem ela, a conexão simplesmente dá timeout. Declare a permissão no manifest de debug (android/app/src/debug/AndroidManifest.xml) e conceda-a:adb shell pm grant <your.app> android.permission.ACCESS_LOCAL_NETWORK.
- Permita http simples para
Mantenha a chave fora do seu código-fonte com --dart-define-from-file, por exemplo
flutter run --dart-define-from-file=lyrelog.local.json e
String.fromEnvironment('LYRELOG_KEY'), com esse arquivo ignorado pelo git.
Isso é só para desenvolvimento local. A ingestão hospedada é um endereço https público e não
precisa de nada disso.
Eventos verificados
Um evento verificado é um evento que não pode ter sido enviado por alguém que copiou a chave de ingestão pública de dentro de um app ou de uma página web. O que isso prova, e o que não prova, está em Eventos verificados.
Os SDKs nativos verificam o app em dispositivos reais (attest, ativado por padrão), e nada muda
no seu código Dart. Configure cada plataforma em que o app é distribuído:
- iOS, com o App Attest da Apple (
verified_byéapp_attest):- Adicione a capability App Attest ao target Runner no Xcode (Signing & Capabilities), o
entitlement
com.apple.developer.devicecheck.appattest-environment. Defina-o comoproductionpara builds da App Store e do TestFlight; sem ele, a Apple usa o ambiente de desenvolvimento. - Adicione o seu App ID, o Team ID, um ponto e o bundle id (
ABCDE12345.com.example.app), em Project settings, na seção Verified events from your Apple apps.
- Adicione a capability App Attest ao target Runner no Xcode (Signing & Capabilities), o
entitlement
- Android, com Key Attestation
(
verified_byékey_attestation): em Project settings, na seção Verified events from your Android apps, adicione o seu pacote e a impressão digital SHA-256 de cada certificado que assina builds que enviam eventos: a chave de assinatura de apps do Play (Play Console, Test and release, App integrity) e, para builds que você mesmo assina, a que o./gradlew signingReportmostra (rode-o na pastaandroiddo seu app).
Para desativar nas duas plataformas:
Lyrelog.start(const LyrelogConfiguration(apiKey: 'lyr_ing_...', attest: false));O envio nunca espera por isso: até o app ter um token, e sempre que algo falhar, os eventos são enviados sem verificação. Enquanto uma plataforma não estiver configurada no projeto, o SDK para de tentar naquela inicialização.
- O simulador do iOS e os emuladores do Android nunca são verificados.
- Um dispositivo que o servidor recusa (um celular com root, um bootloader desbloqueado, um certificado que o projeto não lista) envia eventos não verificados; o Android tenta de novo um dia depois.
- Recusar o consentimento apaga o registro da chave atestada nas duas plataformas.
Antes de fazer o projeto aceitar somente eventos verificados de ios ou android, confira no
explorer se os eventos dos seus usuários reais chegam verificados: eventos de versões antigas, de
simuladores, de emuladores e de dispositivos recusados ficariam retidos com um 425. Nunca
coloque uma chave de servidor (lyr_srv_...) em um app: qualquer coisa distribuída em um app
pode ser lida.
Para conferir, abra o explorer: um evento aberto diz isso em Context, na linha Sender: Verified, App Attest, Verified, Key Attestation ou Not verified, public key.
Configuração
| Opção | Padrão | Significado |
|---|---|---|
apiKey | obrigatória | A chave de ingestão do projeto |
endpoint | https://ingest.lyrelog.com | A URL base; um caminho /v1/... colado é removido. Só https, http apenas para localhost e para o 10.0.2.2 do emulador do Android |
consent | Consent.granted | pending, granted ou denied |
minimumLevel | LogLevel.debug | Eventos abaixo dele são descartados antes de chegar à fila do dispositivo |
flushInterval | 15 s | De quanto em quanto tempo o envio roda em primeiro plano |
maxBatchBytes | 512 KiB | Um lote fecha no limite que chegar primeiro (mantido dentro de 4 MiB) |
maxBatchEvents | 500 | No máximo 2.000 |
maxDiskBytes | 20 MB | Limite da fila em disco, os mais antigos saem primeiro |
maxEventAge | 7 dias | Eventos mais antigos na fila são descartados |
sessionTimeout | 30 min | Tempo de inatividade que inicia uma nova sessão |
environment | detectado | Qualquer nome válido, ou null |
platform | o sistema operacional | Qualquer nome válido, ou null |
redactedKeys | null: defaultRedactedKeys | Nomes de chave a ocultar; a sua lista substitui os padrões, uma lista vazia desativa a ocultação |
captureErrors | true | Reporta os erros de Dart que ninguém capturou |
captureNativeCrashes | true | iOS: crashes, travamentos e relatórios de uso excessivo do MetricKit. Android: exceções da JVM não capturadas. Enviados na próxima inicialização |
attachScreen | true | Marca os eventos com a tela atual |
attest | true | Verifica os eventos com App Attest ou Key Attestation assim que o projeto estiver configurado |
mirrorToConsole | false | Imprime também cada evento no log nativo (console do Xcode, logcat) |
pauseUploadsInLowPowerMode | true | Só no iOS: os envios periódicos pausam; ir para segundo plano continua enviando |
Entrega e limites
A entrega fica por conta do SDK nativo, igual a um app em Swift ou Kotlin:
| iOS | Android | |
|---|---|---|
| Nunca bloqueia | Uma chamada passa o evento para o SDK nativo e retorna; um único writer em segundo plano o grava em disco e nunca espera pela rede. | Igual. |
| Sobrevive a encerramentos forçados e à falta de conexão | Uma fila em Library/Caches, limitada a 20 MB e 7 dias. O sistema pode limpar Caches quando o dispositivo fica sem espaço, e os eventos que estavam esperando vão junto. | Uma fila em noBackupFilesDir/lyrelog, limitada a 20 MB e 7 dias, que nunca entra em backup, então um celular restaurado não reenvia os eventos de outro dispositivo. |
| Quando envia | A cada 15 s em primeiro plano (pausado no Modo de Pouca Energia), e quando o app vai para segundo plano, dentro de uma background task. | A cada 15 s enquanto a Activity do app está iniciada, e quando ele vai para segundo plano. Em segundo plano nada roda por intervalo: o que sobrar sai na próxima inicialização ou na próxima vez que o app vier para a frente. |
| Lotes | Até 500 eventos ou 512 KiB por requisição, com gzip. Um evento com mais de 1 MiB depois de codificado é descartado e contado. | Igual. |
| Novas tentativas | 1 s, dobrando até 5 min, com full jitter, respeitando o Retry-After. Qualquer outro 4xx descarta o lote, um 3xx (um redirecionamento, nunca seguido) o descarta, e uma chave revogada (401, 403) interrompe o envio até a próxima inicialização e mantém os eventos. Um lote que o servidor continua recusando enquanto os outros passam vai para o fim da fila e depois é descartado. | Igual. |
| Cota mensal | Quando uma organização Free já usou os eventos do mês, o servidor responde 429. Os eventos ficam na fila em disco e saem assim que o servidor voltar a aceitá-los, dentro dos limites de 20 MB e 7 dias. Um aviso no unified log (subsistema com.lyrelog.sdk). | Igual, com o aviso no logcat (tag Lyrelog). |
| Descartes visíveis | Os eventos perdidos pelos limites viram um único aviso lyrelog_events_dropped (área lyrelog) com a contagem. | Igual. |
| Os próprios problemas | Um endpoint errado, uma chave recusada ou linhas rejeitadas vão uma vez por inicialização para o unified log, subsistema com.lyrelog.sdk, no nível debug. | Igual, no logcat, tag Lyrelog, no nível debug. |
| Contexto | Id do app, versão, build, sistema operacional, modelo do dispositivo (iPhone18,1), locale, plataforma ios, id da sessão (novo após 30 min de inatividade) e id da instalação. sdk é lyrelog-flutter/0.1.0 lyrelog-swift/0.1.0. | Id do app (o nome do pacote), version name, version code, a versão do Android, o dispositivo (Google Pixel 9), locale, plataforma android, id da sessão e id da instalação. sdk é lyrelog-flutter/0.1.0 lyrelog-android/0.1.0. |
| Segredos | Valores sob chaves cujo nome é ou termina com authorization, cookie, password, token, secret, apikey e o resto da lista compartilhada viram "[redacted]", em qualquer profundidade, antes de qualquer corte. | Igual. |
| Limites | Strings longas são cortadas no limite de um caractere, atributos extras são contados em lyrelog_dropped_attrs, e payloads com mais de 64 KiB são resumidos como {"lyrelog_truncated": true, "bytes": N, "preview": "..."}. | Igual. |
Mude a lista de ocultação com redactedKeys: a sua lista substitui os padrões, e uma lista vazia
desativa a ocultação. Para acrescentar itens:
Lyrelog.start(const LyrelogConfiguration(
apiKey: 'lyr_ing_...',
redactedKeys: [...LyrelogConfiguration.defaultRedactedKeys, 'pin'],
));Privacidade na App Store e segurança dos dados no Play
O manifesto de privacidade do SDK de Swift (PrivacyInfo.xcprivacy) vai dentro do app, e o
Xcode o incorpora ao relatório de privacidade do app, como na
página de Swift.
Para o rótulo de privacidade da App Store, declare o que o seu app envia pelo Lyrelog:
- Diagnostics: Crash Data, Performance Data, Other Diagnostic Data (App Functionality).
- Identifiers > Device ID: o id da instalação, um UUID aleatório que não é o id de
publicidade, não entra em backup e é apagado quando o consentimento é negado (App Functionality). Não vinculado à
pessoa, a menos que você também chame
setUser. - Identifiers > User ID, vinculado à pessoa: só se você chamar
setUser. - Usage Data > Product Interaction: se você registrar telas (
screen_viewed) ou toques.
No formulário de segurança dos dados do Play Console:
- App info and performance: Crash logs, Diagnostics (App functionality, e Analytics se você usar dessa forma). Coletados, não compartilhados.
- Device or other IDs: o id da instalação, como acima.
- App activity > App interactions: se você registrar telas ou toques.
Nos dois casos, qualquer outra coisa que os seus attrs ou payload levem (emails, compras...)
entra na categoria correspondente. Os dados são criptografados em trânsito (https). O servidor
acrescenta o país do endereço de envio; o endereço em si não é armazenado.