Começar a usar o Crashlytics para Web

Selecionar plataforma:

iOS+ Android Android NDK Web Flutter Unity

Pré-lançamento: o Crashlytics para apps da Web é uma versão de pré-lançamento. Uma versão de pré-lançamento não está sujeita a SLAs ou políticas de descontinuação e pode mudar de maneira incompatível com versões anteriores.

Este guia descreve como começar a usar o Firebase Crashlytics no app da Web.

Depois de configurar o SDK do Firebase Crashlytics no app, você pode receber relatórios de erros abrangentes no console do Firebase. Com o Crashlytics para apps da Web, você recebe relatórios de erros.

Importante: o suporte do Crashlytics para apps da Web será lançado nos próximos dias. Se você ainda não encontrar a experiência no console do Firebase, volte em breve.

Antes de começar

A configuração do Crashlytics exige tarefas no console do Firebase e no ambiente de desenvolvimento integrado, como adicionar a configuração do Firebase do seu app e o SDK do Crashlytics. Para concluir a configuração, você terá que forçar uma falha de teste para enviar seu primeiro relatório de erros ao Firebase.

Para configurar manualmente o Crashlytics no seu app da Web, verifique se você concluiu os seguintes pré-requisitos:

• Crie um Projeto do Firebase e um App do Firebase, se ainda não tiver um. Adicione o Firebase ao seu projeto JavaScript, caso ainda não tenha feito isso.

• Verifique se a sua conta tem permissões de proprietário no projeto. Isso é necessário para ativar as APIs e os papéis do IAM necessários.

• Verifique se o projeto do Firebase está no plano de preços Blaze de pagamento por uso. O Crashlytics para Web usa o Cloud Logging para armazenamento de telemetria e o Cloud Storage para armazenamento de mapas de origem, que são produtos pagos com um nível sem custo financeiro. Saiba mais sobre os preços do Logging e do Cloud Storage.

Etapa 1: ativar o Crashlytics no seu app da Web

O Crashlytics para Web usa o Cloud Logging, o Error Reporting e o Cloud Storage. Portanto, é necessário ativar essas APIs e configurar as permissões para seu projeto. É possível ativar o Crashlytics para seu app da Web usando o console do Firebase ou a CLI do Firebase.

Use o console Firebase

1. No console do Firebase, acesse DevOps e engajamento > painel do Crashlytics.

2. Selecione seu app da Web no seletor suspenso na parte de cima da página.

3. Clique em Configurar o Crashlytics e siga as instruções na tela.

Usar a CLI Firebase

Importante: embora o suporte do Crashlytics para apps da Web seja lançado nos próximos dias, recomendamos usar o console do Firebase para a configuração. Se você usar a CLI Firebase agora para configurar o Crashlytics, talvez não seja possível ver as falhas no painel do Crashlytics até o final desta semana.

Se preferir configurar o projeto no terminal ou usar um agente de programação de IA, use a CLI Firebase:

1. Verifique se você tem a CLI do Firebase v15.35.0 ou mais recente instalada e se você está autenticado (firebase login). Saiba como instalar ou atualizar a CLI do Firebase.

2. Execute o seguinte comando para configurar o Crashlytics no seu app da Web:

   firebase crashlytics:setup \
     --app FIREBASE_APP_ID \
     --project PROJECT_ID
   

   Esse comando executa as seguintes etapas de configuração:

   • Verifica se o projeto está no plano de preços Blaze de pagamento por uso e solicita que você faça upgrade, se necessário.

   • Ativa as APIs de telemetria e Crashlytics necessárias (firebasetelemetry.googleapis.com, firebasetelemetryadmin.googleapis.com, firebasecrashlytics.googleapis.com e clienttelemetry.googleapis.com).

   • Se a chave de API do seu app da Web tiver restrições de API, adicione clienttelemetry.googleapis.com às APIs permitidas.

   • Define as configurações de telemetria do Crashlytics para seu app da Web.

   • Quando executado de forma interativa, solicita que você ative os alertas por e-mail para problemas novos e regredidos.

Etapa 2: adicionar e inicializar o SDK no app

1. Instale o SDK Crashlytics:

   npm install firebase
   

2. Inicialize a instância FirebaseApp:

   Crie um arquivo de utilitário de configuração central para usar a inicialização de singleton. Para encontrar os valores de configuração do app do Firebase, acesse Configurações do projeto > página Geral no console do Firebase, acesse o card Seus apps e selecione seu app da Web.

   // src/lib/firebase.ts
   import { initializeApp, getApps, getApp } from '@firebase/app';
   
   const firebaseConfig = {
     apiKey: "API_KEY",
     authDomain: "AUTH_DOMAIN",
     projectId: "PROJECT_ID",
     storageBucket: "STORAGE_BUCKET",
     messagingSenderId: "MESSAGING_SENDER_ID",
     appId: "FIREBASE_APP_ID"
   };
   
   // Guarantee singleton initialization across renders or module refreshes
   export const app = getApps().length === 0
     ? initializeApp(firebaseConfig)
     : getApp();
   

Etapa 3: configurar a captura automática de erros para seu framework

Os receptores automáticos de erros do framework e os rastreadores manuais usam sua instância compartilhada de FirebaseApp. Selecione seu framework para configurar a captura automática de erros:

Angular

Faça a integração com o ambiente de execução global de captura de erros do Angular e o rastreamento automático de rotas adicionando provideCrashlytics(() => app) aos provedores do seu app em src/app/app.config.ts:

// src/app/app.config.ts
import { ApplicationConfig } from '@angular/core';
import { provideRouter } from '@angular/router';
import { provideCrashlytics } from '@firebase/crashlytics/angular';
import { app } from '../lib/firebase'; // Shared initialization script
import { routes } from './app.routes';

export const appConfig: ApplicationConfig = {
  providers: [
    provideRouter(routes),
    provideCrashlytics(() => app)
  ]
};

Observação: o provideCrashlytics registra um ErrorHandler personalizado para rastrear falhas de zona não capturadas (Zone.js) e usa instâncias internas de Router para criar rotas dinâmicas (como /dashboard/user/:id) em vez de registrar URLs literais, mantendo a telemetria livre de informações de identificação pessoal.

Next.js

Next.js 15.3+ (recomendado): instrumentação do cliente (instrumentation-client.ts)

O Next.js 15.3+ inclui instrumentação nativa do lado do cliente usando instrumentation-client.ts (ou instrumentation-client.js). O Next.js executa esse arquivo no navegador antes do início da hidratação do React.

Crie src/instrumentation-client.ts (ou instrumentation-client.ts na raiz do projeto, se não estiver usando um diretório src/) e inicialize Crashlytics:

// src/instrumentation-client.ts
import { getCrashlytics } from '@firebase/crashlytics';
import { app } from './lib/firebase'; // Shared initialization script

getCrashlytics(app);

Esse arquivo único inicializa o Crashlytics antes da hidratação do React e registra automaticamente listeners de erros globais (error e unhandledrejection) sem modificações no src/app/layout.tsx ou em qualquer componente do React.

Next.js < 15.3: lado do cliente (layout do roteador de apps)

Para versões do Next.js anteriores à 15.3, layout.tsx é um componente de servidor por padrão. Como FirebaseApp não é serializável, envolva <FirebaseCrashlytics> (de @firebase/crashlytics/react para inicializar Crashlytics e capturar erros não detectados) em um componente do cliente (como src/components/CrashlyticsProvider.tsx) marcado com a diretiva 'use client':

// src/components/CrashlyticsProvider.tsx
'use client';

import React from 'react';
import { FirebaseCrashlytics } from '@firebase/crashlytics/react';
import { app } from '../lib/firebase'; // Shared initialization script

export function CrashlyticsProvider({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <>
      <FirebaseCrashlytics firebaseApp={app} />
      {children}
    </>
  );
}

Em seguida, envolva o layout raiz com <CrashlyticsProvider>:

// src/app/layout.tsx
import React from 'react';
import { CrashlyticsProvider } from '../components/CrashlyticsProvider';

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        <CrashlyticsProvider>
          {children}
        </CrashlyticsProvider>
      </body>
    </html>
  );
}

React (sem o React Router)

Envolva o componente raiz do app (geralmente src/App.tsx ou src/main.tsx) com o componente de limite de erro <FirebaseCrashlytics>. Ele atua como o receptor global, processando rejeições e exceções não processadas do navegador e da interface do React. Ele envolve todas as hierarquias de componentes filhos e captura automaticamente exceções não detectadas ou erros de roteamento:

// src/App.tsx
import React from 'react';
import { FirebaseCrashlytics } from '@firebase/crashlytics/react';
import { app } from './lib/firebase'; // Shared initialization script

export default function App({
  children,
}: {
  children?: React.ReactNode;
}) {
  return (
    <FirebaseCrashlytics firebaseApp={app}>
      {children}
    </FirebaseCrashlytics>
  );
}

React Router (v6+)

Se você estiver usando o React Router v6+, substitua o contêiner <Routes> do React Router por <CrashlyticsRoutes>. Isso mapeia automaticamente os limites de erro em rotas e rastreia erros usando nomes de caminho com modelo, como /profile/:userId:

// src/App.tsx
import React from 'react';
import { BrowserRouter, Route } from 'react-router-dom';
import { CrashlyticsRoutes } from '@firebase/crashlytics/react-router';
import { app } from './lib/firebase'; // Shared initialization script
import Home from './pages/Home';
import Profile from './pages/Profile';
import Product from './pages/Product';

export default function App() {
  return (
    <BrowserRouter>
      <CrashlyticsRoutes firebaseApp={app}>
        <Route path="/" element={<Home />} />
        <Route path="/profile/:userId" element={<Profile />} />
        <Route path="/product/:productId/details" element={<Product />} />
      </CrashlyticsRoutes>
    </BrowserRouter>
  );
}

TanStack Router

Se o app usa o TanStack Router, inicialize Crashlytics com getCrashlytics(app) e anexe o registro de erros padrão diretamente na configuração da instância do roteador (defaultOnCatch):

import { recordError, getCrashlytics } from '@firebase/crashlytics';
import { app } from './lib/firebase'; // Shared initialization script

import { createRouter } from '@tanstack/react-router';
import { routeTree } from './routeTree.gen';

const crashlytics = getCrashlytics(app);

const router = createRouter({
  routeTree,
  defaultOnCatch: (error, errorInfo) => {
    recordError(crashlytics, error, errorInfo);
  },
});

Observação: chamar getCrashlytics(app) registra automaticamente listeners globais para erros de janela não capturados e rejeições de promessa não processadas, enquanto defaultOnCatch captura erros capturados durante o roteamento e a renderização de componentes no TanStack Router.

(Opcional) Etapa 4: configurar o controle de versões do app

É altamente recomendável adicionar uma string de versão clara aos builds do seu app da Web para isolar as regressões em implantações específicas. Transmita appVersion em CrashlyticsOptions ao inicializar o SDK do Crashlytics para seu framework (usando uma string de lançamento ou uma variável de ambiente de tempo de build, como process.env.NEXT_PUBLIC_APP_VERSION ou import.meta.env.VITE_APP_VERSION):

Angular

Transmita um objeto CrashlyticsOptions com appVersion como o segundo argumento para provideCrashlytics em src/app/app.config.ts:

// src/app/app.config.ts
import { ApplicationConfig } from '@angular/core';
import { provideRouter } from '@angular/router';
import { provideCrashlytics } from '@firebase/crashlytics/angular';
import { app } from '../lib/firebase'; // Shared initialization script
import { routes } from './app.routes';

export const appConfig: ApplicationConfig = {
  providers: [
    provideRouter(routes),
    provideCrashlytics(() => app, {
      appVersion: 'APP_VERSION'
    })
  ]
};

Next.js

Next.js 15.3+ (recomendado): instrumentação do cliente (instrumentation-client.ts)

Transmita um objeto CrashlyticsOptions com appVersion como o segundo argumento para getCrashlytics em src/instrumentation-client.ts:

// src/instrumentation-client.ts
import { getCrashlytics } from '@firebase/crashlytics';
import { app } from './lib/firebase'; // Shared initialization script

getCrashlytics(app, {
  appVersion: 'APP_VERSION'
});

Next.js < 15.3: lado do cliente (layout do roteador de apps)

Transmita crashlyticsOptions com appVersion para <FirebaseCrashlytics> em src/components/CrashlyticsProvider.tsx:

// src/components/CrashlyticsProvider.tsx
'use client';

import React from 'react';
import { FirebaseCrashlytics } from '@firebase/crashlytics/react';
import { app } from '../lib/firebase'; // Shared initialization script

const crashlyticsOptions = {
  appVersion: 'APP_VERSION'
};

export function CrashlyticsProvider({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <>
      <FirebaseCrashlytics
        firebaseApp={app}
        crashlyticsOptions={crashlyticsOptions}
      />
      {children}
    </>
  );
}

React (sem o React Router)

Transmita crashlyticsOptions com appVersion para <FirebaseCrashlytics> em src/App.tsx:

// src/App.tsx
import React from 'react';
import { FirebaseCrashlytics } from '@firebase/crashlytics/react';
import { app } from './lib/firebase'; // Shared initialization script

const crashlyticsOptions = {
  appVersion: 'APP_VERSION'
};

export default function App({
  children,
}: {
  children?: React.ReactNode;
}) {
  return (
    <FirebaseCrashlytics
      firebaseApp={app}
      crashlyticsOptions={crashlyticsOptions}
    >
      {children}
    </FirebaseCrashlytics>
  );
}

React Router (v6+)

Transmita crashlyticsOptions com appVersion para <CrashlyticsRoutes> em src/App.tsx:

// src/App.tsx
import React from 'react';
import { BrowserRouter, Route } from 'react-router-dom';
import { CrashlyticsRoutes } from '@firebase/crashlytics/react-router';
import { app } from './lib/firebase'; // Shared initialization script
import Home from './pages/Home';
import Profile from './pages/Profile';
import Product from './pages/Product';

const crashlyticsOptions = {
  appVersion: 'APP_VERSION'
};

export default function App() {
  return (
    <BrowserRouter>
      <CrashlyticsRoutes
        firebaseApp={app}
        crashlyticsOptions={crashlyticsOptions}
      >
        <Route path="/" element={<Home />} />
        <Route path="/profile/:userId" element={<Profile />} />
        <Route path="/product/:productId/details" element={<Product />} />
      </CrashlyticsRoutes>
    </BrowserRouter>
  );
}

TanStack Router

Transmita um objeto CrashlyticsOptions com appVersion como o segundo argumento para getCrashlytics:

import { recordError, getCrashlytics } from '@firebase/crashlytics';
import { app } from './lib/firebase'; // Shared initialization script

import { createRouter } from '@tanstack/react-router';
import { routeTree } from './routeTree.gen';

const crashlytics = getCrashlytics(app, {
  appVersion: 'APP_VERSION'
});

const router = createRouter({
  routeTree,
  defaultOnCatch: (error, errorInfo) => {
    recordError(crashlytics, error, errorInfo);
  },
});

Etapa 5: forçar uma falha de teste

Para concluir a configuração do Crashlytics e conferir os dados iniciais no painel do Crashlytics no console do Firebase, é necessário forçar uma falha de teste.

1. Adicione um código ao app que possa ser usado para forçar uma falha no teste.

   Adicione um botão de teste ou um acionador de rota ao seu app React, Next.js ou Angular que gere um erro de tempo de execução quando clicado:

   // Trigger an unhandled exception on button click or route load
   function handleTestCrash() {
     throw new Error("Crashlytics Web SDK Test Unhandled Error!");
   }
   

   Se você configurou a captura automática de erros com <FirebaseCrashlytics> (React ou Next.js), provideCrashlytics (Angular) ou <CrashlyticsRoutes> (React Router), o lançamento desse erro captura automaticamente a exceção e a programa para upload.

2. Crie e execute o app e acione o erro de teste para que ele envie o primeiro relatório de falhas ao Firebase.

3. No console do Firebase, acesse o painel DevOps e engajamento > Crashlytics para verificar o relatório de falhas do teste:

   1. Selecione seu app da Web no seletor suspenso na parte de cima da página.

   2. Atualize a página. A exceção de teste vai aparecer na tabela Problemas em alguns minutos.

Se você atualizou o console e ainda não consegue ver a falha de teste após cinco a dez minutos, consulte Resolver problemas de configuração.

O Crashlytics está monitorando seu app da Web em busca de erros. Acesse o painel do Crashlytics para ver e analisar todos os relatórios e estatísticas.

Próximas etapas

• Receba relatórios de erros legíveis: configure o upload automático do mapa de origem (.js.map) para que os stack traces de produção mostrem os nomes de arquivo e números de linha originais.
• Personalizar relatórios de erros: saiba como informar exceções tratadas, adicionar chaves personalizadas, forçar a limpeza de registros de telemetria e configurar a amostragem.