SDK Flutter

CrashLensOptions

Classe de configuração passada para CrashLens.init().

CrashLens.init()

Método estático que inicializa o SDK. Deve ser chamado antes do runApp().

static Future<void> init({
  required CrashLensOptions options,
})

Ao inicializar, o SDK automaticamente:

• Coleta informações do dispositivo e do app
• Reenvia eventos pendentes de execuções anteriores
• Configura a fila de eventos com flush automático
• Instala handlers para FlutterError, PlatformDispatcher e zonas
• Inicia uma nova sessão de rastreamento

CrashLens.captureException()

Captura uma exceção manualmente e a envia para o CrashLens.

static void captureException(
  dynamic error,
  StackTrace? stackTrace, {
  bool handled = true,
  String? context,
  Map<String, dynamic>? tags,
  Map<String, dynamic>? extra,
})

Exemplo de uso:

try {
  // código que pode lançar exceção
} catch (e, s) {
  CrashLens.captureException(e, s, handled: true);
}

CrashLens.captureMessage()

Captura uma mensagem de log manualmente.

static void captureMessage(
  String message, {
  EventSeverity severity = EventSeverity.info,
  Map<String, dynamic>? tags,
  Map<String, dynamic>? extra,
})

Exemplo:

CrashLens.captureMessage(
  'Usuário fez login com sucesso',
  severity: EventSeverity.info,
);

CrashLens.captureEvent()

Captura um evento personalizado com controle total sobre todos os campos.

static void captureEvent({
  required String message,
  EventSeverity severity = EventSeverity.info,
  dynamic exceptionType,
  String? exceptionMessage,
  String? stackTrace,
  String? fingerprint,
  String? context,
  Map<String, dynamic>? tags,
  Map<String, dynamic>? extra,
})

Breadcrumbs

Breadcrumbs são eventos de rastreamento que ajudam a entender a sequência de ações que levaram a um erro.

CrashLens.addBreadcrumb()

static void addBreadcrumb(Breadcrumb breadcrumb)

Classe Breadcrumb

Exemplo:

CrashLens.addBreadcrumb(Breadcrumb(
  message: 'Usuário clicou no botão de confirmação',
  type: BreadcrumbType.gesture,
  category: 'ui.interaction',
));

Gerenciamento de Usuário

CrashLensUser

Representa o usuário atual associado ao aplicativo. Similar ao SentryUser.

CrashLens.setUser()

CrashLens.setUser(CrashLensUser(
  id: 'user-123',
  email: 'usuario@exemplo.com',
));

Tags Globais

Gerencie tags que são enviadas com todos os eventos:

// Adicionar tag
CrashLens.setTag('versao_ui', '2.1.0');

// Remover tag
CrashLens.removeTag('versao_ui');

Sessões

O CrashLens rastreia automaticamente sessões de usuário. Uma sessão é iniciada na inicialização do SDK e finalizada ao chamar CrashLens.endSession()ou CrashLens.close().

Se um erro fatal ou não tratado ocorrer durante a sessão, ela é marcada automaticamente como crashed. O backend calcula a taxa de crash-free rate baseada nas sessões.

CrashLens.endSession()

Encerra a sessão atual manualmente (ex.: ao colocar o app em background).

static Future<void> endSession()

CrashLens.sessionId

Retorna o ID da sessão atual, útil para vincular a erros manualmente.

static String? get sessionId

CrashLens.markSessionCrashed()

Marca manualmente a sessão atual como crashed.

static void markSessionCrashed()

Exemplo de gerenciamento do ciclo de vida:

@override
void didChangeAppLifecycleState(AppLifecycleState state) {
  if (state == AppLifecycleState.paused) {
    CrashLens.endSession(); // app foi para background
  }
}

CrashLensNavigatorObserver

Observer que captura automaticamente a navegação entre rotas Flutter e gera breadcrumbs para cada transição (push, pop, replace, remove).

MaterialApp(
  navigatorObservers: [
    CrashLensNavigatorObserver(),
  ],
)

CrashLensDioInterceptor

Interceptor do Dio que captura automaticamente requisições HTTP. Gera breadcrumbs para cada requisição e captura eventos de erro em chamadas com status code 4xx/5xx.

Parâmetros

final dio = Dio()
  ..interceptors.add(CrashLensDioInterceptor(
    sanitizeHeaders: ['Authorization', 'Cookie'],
    sanitizeBodyKeys: ['password', 'token'],
  ));

CrashLensHttpClient

Wrapper para o pacote http que captura automaticamente requisições HTTP. Gera breadcrumbs e captura eventos de erro em chamadas com falha.

Parâmetros

import 'package:http/http.dart' as http;

final client = CrashLensHttpClient(
  http.Client(),
  sanitizeHeaders: ['Authorization', 'Cookie'],
  sanitizeBodyKeys: ['password', 'token'],
  maxBodySize: 4096, // tamanho máx. do body capturado
);

final response = await client.get(Uri.parse('https://api.exemplo.com/data'));

beforeSend

Callback que permite modificar ou descartar eventos antes de serem enviados. Retorne o evento modificado, ou null para descartá-lo.

CrashLens.init(
  options: CrashLensOptions(
    apiKey: 'sua-api-key',
    beforeSend: (event) {
      // Modificar severidade para erros HTTP
      if (event.error is DioException) {
        return event.copyWith(
          severity: EventSeverity.warning,
          extra: {
            ...?event.extra,
            'http_status': (event.error as DioException)
                .response?.statusCode,
          },
        );
      }
      // Descartar erros de debug
      if (event.message.contains('debug')) return null;
      return event;
    },
  ),
);

CrashLens.flush()

Força o envio imediato de todos os eventos pendentes na fila.

static Future<void> flush()

Exemplo:

await CrashLens.flush();

CrashLens.close()

Encerra o SDK, enviando eventos pendentes, removendo handlers e finalizando a sessão atual.

static Future<void> close()

Status da Instância

Propriedades da instância para verificar o estado do SDK:

Erros Locais (Depuração)

Com a opção captureLocally: true, o SDK persiste todos os eventos no armazenamento local do dispositivo via SharedPreferences. Útil para depuração sem depender da conexão com o backend.

// Listar erros locais
final errors = CrashLens.localErrors;
// ou:
final errors = CrashLens.getLocalErrors();

// Remover um erro específico
await CrashLens.deleteLocalError(eventId);

// Limpar todos os erros locais
await CrashLens.clearLocalErrors();

Fingerprint Inteligente

O CrashLens gera automaticamente um fingerprint único para cada evento usando SHA-256 do conteúdo completo (mensagem, tipo da exceção, stack trace, contexto, tags, etc.). Isso permite agrupar eventos idênticos e evitar duplicatas no backend.

O fingerprint é computado automaticamente se não for fornecido manualmente via captureEvent(fingerprint: '...').

// O método estático computeEventHash pode ser usado diretamente:
final hash = CrashLens.computeEventHash(event);

Armazenamento Offline e Retry

O SDK conta com uma fila de eventos com suporte a retry e persistência offline:

• Eventos são enfileirados e enviados em lote a cada 5 segundos (configurável via flushIntervalSeconds)
• Em caso de falha de rede, o evento é retentado até 3 vezes (configurável via maxRetries)
• Eventos não enviados são persistidos no SharedPreferences e reenviados na próxima inicialização do app
• Se o plano do workspace atingir o limite (HTTP 402/429), o SDK pausa automaticamente e tenta retomar a cada 15 minutos

EventSeverity

Enum que define a severidade de um evento:

BreadcrumbType