• Flutter 3.41 ou mais recente (Dart SDK ^3.0.0).
• Um backend do OpenReplay na versão v1.26.0 ou mais recente. Backends mais antigos não informam suporte a frames: os eventos ainda são gravados, mas a tela não.

O pacote não tem dependências do pub — o protocolo de comunicação, o batching, o gzip e o multipart são todos implementados em Dart, e tudo o que é nativo passa por um único platform channel.

flutter pub add openreplay

Ou adicione-o ao seu pubspec.yaml:

dependencies:
  openreplay: ^1.0.9

Você deve passar o projectKey para start(). Você pode obter esse valor no seu dashboard do OpenReplay em ‘Preferences > Projects’.

Envolva o seu app em OpenReplayWidget e depois inicie o tracker. O wrapper é obrigatório: ele fornece o repaint boundary de onde os frames são capturados, então, sem ele, nada é gravado.

import 'package:flutter/material.dart';
import 'package:openreplay/openreplay.dart';

void main() {
  runApp(const OpenReplayWidget(child: MyApp()));
}

class _MyAppState extends State<MyApp> {
  @override
  void initState() {
    super.initState();
    WidgetsBinding.instance.addPostFrameCallback((_) async {
      await OpenReplay.instance.start(
        projectKey: 'YOUR_PROJECT_KEY',
        // not required if you're using our SaaS version
        serverUrl: 'https://your.instance.com/ingest',
      );
    });
  }

  @override
  Widget build(BuildContext context) => MaterialApp(
        // records screen transitions
        navigatorObservers: [ORNavigatorObserver()],
        home: const HomePage(),
      );
}

start() pode ser chamado com segurança antes do primeiro frame — a captura só começa depois que o OpenReplayWidget concluir o layout.

Adicione ORNavigatorObserver ao seu MaterialApp (ou CupertinoApp, ou qualquer Navigator) para que as rotas empilhadas e removidas apareçam na timeline do replay:

MaterialApp(
  navigatorObservers: [ORNavigatorObserver()],
  // ...
)

As rotas são reportadas por route.settings.name. Rotas sem nome usam como alternativa a sua posição na pilha (route/2), então rotas nomeadas geram timelines muito mais legíveis.

Veja como sanitizar dados em replays do Flutter para mais detalhes.

As opções são passadas como OROptions para start():

await OpenReplay.instance.start(
  projectKey: 'YOUR_PROJECT_KEY',
  options: const OROptions(
    logs: false,
    targetLongEdge: 1080,
  ),
);

• crashes: bool Captura erros do Dart. Crashes nativos ainda precisam de um reporter nativo. Padrão: true.
• analytics: bool Captura toques, deslizes, telas e inputs. Padrão: true.
• performances: bool Captura CPU, memória, bateria e estado térmico. Padrão: true.
• logs: bool Captura a saída de debugPrint. Padrão: true.
• screen: bool Habilita a captura de frames. Padrão: true.
• screenshotBatchSize: ScreenshotBatchSize Frames mantidos em buffer antes de um lote ser empacotado e enviado — low (10), normal (20) ou high (30). Padrão: normal.
• targetLongEdge: int Maior lado de um frame capturado, em pixels. Limita o custo por frame para que ele não oscile conforme o tamanho da tela. Padrão: 720.
• dedupeFrames: bool Ignora frames cujos pixels sejam idênticos, byte a byte, aos do frame anterior. A reprodução não é afetada — o player mantém o último snapshot igual ou anterior ao instante atual. Padrão: true.
• maskPlatformViews: bool Cobre as platform views (WebView, mapas, preview da câmera) com um placeholder. Elas são renderizadas em camadas nativas que o Flutter não consegue ler de volta, então, sem isso, aparecem em branco. Padrão: true.
• wifiOnly: bool Reservado; ainda não aplicado. Padrão: true.
• debugLogs: bool Habilita o logging do próprio SDK. Padrão: false.
• debugImages: bool Despeja os frames capturados para depuração. Padrão: false.

Dois presets são fornecidos: OROptions.defaults (todos os itens acima) e OROptions.defaultDebug (o mesmo, com debugLogs: true).

serverUrl usa o OpenReplay Cloud por padrão. Implantações auto-hospedadas passam esse valor para start() ou o definem antecipadamente:

OpenReplay.instance.serverUrl = 'https://your.instance.com/ingest';

Se você tiver qualquer dúvida sobre este processo, fale com a gente no nosso Slack.