Acesso antecipadoSó por convite, e os SDKs ainda não foram publicados.Pedir um convite
Ir para o conteúdo
Docs

Flutter

Logs estruturados do seu app Flutter no iOS e no Android, por cima dos SDKs nativos do Lyrelog.

Apps iOS e Android, sobre os SDKs nativos

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 lyrelog

Ou no pubspec.yaml:

dependencies:
  lyrelog: ^0.1.0

Configuraçã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 minSdk pode 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-out

await 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:

mechanismOrigemO payload também tem
flutter_errorFlutterError.onError: erros ao construir, fazer o layout ou pintar widgets, e em callbacks de gestoslibrary (widgets library) e context (building MyWidget)
platform_dispatcherPlatformDispatcher.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:

PlataformaEventosOrigem
iOSapp_crashed (critical), app_hung (error), cpu_overuse, disk_write_overuse, slow_launch (warnings)MetricKit, como na página de Swift
Androidapp_crashed (critical) com handled: false e mechanism: uncaught_exceptionExceçõ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: development para um build de debug, qualquer build no simulador ou um build com um provisioning profile embutido (assinatura de development e ad hoc); testflight para um build do TestFlight; production nos outros casos. Depois, a resposta do StoreKit, como na página de Swift.
  • Android: development quando o app é depurável (todo build de debug), production nos 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).

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 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 stop

flush 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.1 e 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.2 e 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_NETWORK para acessar um endereço privado como 10.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.

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 como production para 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.
  • 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 signingReport mostra (rode-o na pasta android do 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çãoPadrãoSignificado
apiKeyobrigatóriaA chave de ingestão do projeto
endpointhttps://ingest.lyrelog.comA URL base; um caminho /v1/... colado é removido. Só https, http apenas para localhost e para o 10.0.2.2 do emulador do Android
consentConsent.grantedpending, granted ou denied
minimumLevelLogLevel.debugEventos abaixo dele são descartados antes de chegar à fila do dispositivo
flushInterval15 sDe quanto em quanto tempo o envio roda em primeiro plano
maxBatchBytes512 KiBUm lote fecha no limite que chegar primeiro (mantido dentro de 4 MiB)
maxBatchEvents500No máximo 2.000
maxDiskBytes20 MBLimite da fila em disco, os mais antigos saem primeiro
maxEventAge7 diasEventos mais antigos na fila são descartados
sessionTimeout30 minTempo de inatividade que inicia uma nova sessão
environmentdetectadoQualquer nome válido, ou null
platformo sistema operacionalQualquer nome válido, ou null
redactedKeysnull: defaultRedactedKeysNomes de chave a ocultar; a sua lista substitui os padrões, uma lista vazia desativa a ocultação
captureErrorstrueReporta os erros de Dart que ninguém capturou
captureNativeCrashestrueiOS: crashes, travamentos e relatórios de uso excessivo do MetricKit. Android: exceções da JVM não capturadas. Enviados na próxima inicialização
attachScreentrueMarca os eventos com a tela atual
attesttrueVerifica os eventos com App Attest ou Key Attestation assim que o projeto estiver configurado
mirrorToConsolefalseImprime também cada evento no log nativo (console do Xcode, logcat)
pauseUploadsInLowPowerModetrueSó 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:

iOSAndroid
Nunca bloqueiaUma 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ãoUma 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 enviaA 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.
LotesAté 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 tentativas1 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 mensalQuando 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íveisOs eventos perdidos pelos limites viram um único aviso lyrelog_events_dropped (área lyrelog) com a contagem.Igual.
Os próprios problemasUm 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.
ContextoId 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.
SegredosValores 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.
LimitesStrings 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.