Начало работы с Crashlytics для веб-приложений

Выберите платформу:

iOS+ Android Android NDK Web Flutter Unity

Предварительная версия. Crashlytics для веб-приложений – это предварительная версия. На предварительные выпуски не распространяются соглашения об уровне обслуживания и правила прекращения поддержки. В них могут вноситься изменения, при которых не обеспечивается обратная совместимость.

В этом руководстве рассказывается, как начать работу с Firebase Crashlytics в веб-приложении.

После настройки SDK Firebase Crashlytics в приложении вы сможете получать подробные отчеты о сбоях в консоли Firebase. Crashlytics для веб-приложений позволяет получать отчеты об ошибках.

Важно! Поддержка Crashlytics в веб-приложениях будет добавлена в ближайшие несколько дней. Если вы пока не видите его в консоли Firebase, проверьте позже.

Подготовка

Чтобы настроить Crashlytics, нужно выполнить действия как в консоли Firebase, так и в интегрированной среде разработки (например, добавить конфигурацию Firebase для приложения и SDK Crashlytics). Чтобы завершить настройку, вам нужно принудительно вызвать тестовый сбой и отправить первый отчет о нем в Firebase.

Чтобы вручную настроить Crashlytics в веб-приложении, выполните следующие действия:

• Создайте проект и приложение Firebase, если у вас их ещё нет. Если вы ещё этого не сделали, добавьте Firebase в проект JavaScript.

• Убедитесь, что у вашего аккаунта есть разрешения владельца проекта. Это необходимо для включения нужных API и ролей IAM.

• Убедитесь, что в проекте Firebase используется тарифный план Blaze с оплатой по мере использования. Crashlytics для веб-приложений использует Cloud Logging для хранения телеметрии и Cloud Storage для хранения файлов исходного кода. Это платные продукты с бесплатным уровнем. Подробнее о ценах на Logging и Cloud Storage…

Шаг 1. Включите Crashlytics для веб-приложения

Crashlytics для веб-приложений использует Cloud Logging, Error Reporting и Cloud Storage, поэтому вам нужно включить эти API и настроить разрешения для проекта. Вы можете включить Crashlytics для своего веб-приложения с помощью консоли Firebase или интерфейса командной строки Firebase.

Используйте консоль Firebase

1. В консоли Firebase перейдите в раздел DevOps & Engagement (DevOps и вовлечение) > Crashlytics dashboard (Панель управления).

2. Выберите веб-приложение в раскрывающемся списке вверху страницы.

3. Нажмите Настроить Crashlytics и следуйте инструкциям на экране.

Как использовать CLI Firebase

Важно! Поддержка веб-приложений в Crashlytics будет добавлена в ближайшие несколько дней. Пока мы рекомендуем использовать для настройки консоль Firebase. Если вы используете интерфейс командной строки Firebase для настройки Crashlytics, то можете не увидеть сбои на панели управления Crashlytics до конца этой недели.

Если вы предпочитаете настраивать проект из терминала или использовать ИИ-агента для написания кода, вы можете использовать CLI Firebase:

1. Убедитесь, что у вас установлена версия 15.35.0 или более поздняя Firebase CLI и что вы прошли аутентификацию (firebase login). Узнайте, как установить или обновить Firebase CLI.

2. Чтобы настроить Crashlytics для веб-приложения, выполните следующую команду:

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

   Эта команда выполняет следующие действия:

   • Проверяет, используется ли в вашем проекте тарифный план Blaze с оплатой по мере использования, и при необходимости предлагает перейти на него.

   • Включает необходимые API Crashlytics и телеметрии (firebasetelemetry.googleapis.com, firebasetelemetryadmin.googleapis.com, firebasecrashlytics.googleapis.com и clienttelemetry.googleapis.com).

   • Если у ключа API вашего веб-приложения есть ограничения API, добавьте clienttelemetry.googleapis.com в список разрешенных API.

   • Задает настройки телеметрии Crashlytics для веб-приложения.

   • При интерактивном запуске предлагает включить оповещения по электронной почте о новых и повторных проблемах.

Шаг 2. Добавьте и инициализируйте SDK в приложении

1. Установите SDK Crashlytics:

   npm install firebase
   

2. Инициализируйте экземпляр FirebaseApp:

   Создайте центральный файл конфигурации, чтобы использовать инициализацию синглтона. Чтобы найти значения конфигурации приложения Firebase, в консоли Firebase перейдите в раздел Project settings (Настройки проекта) > General (Общие), найдите карточку Your apps (Ваши приложения) и выберите веб-приложение.

   // 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();
   

Шаг 3. Настройте автоматическую регистрацию ошибок для своего фреймворка

Как автоматические получатели ошибок фреймворка, так и ручные трекеры используют общий экземпляр FirebaseApp. Выберите фреймворк, чтобы настроить автоматическую регистрацию ошибок:

Angular

Чтобы интегрировать SDK с глобальной средой выполнения Angular, которая перехватывает ошибки, и автоматическим отслеживанием маршрутов, добавьте provideCrashlytics(() => app) в поставщики приложения в файле 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)
  ]
};

Примечание. provideCrashlytics регистрирует пользовательский ErrorHandler для отслеживания неперехваченных сбоев зоны (Zone.js) и использует внутренние экземпляры Router для создания динамических маршрутов (например, /dashboard/user/:id), а не для регистрации буквальных URL, чтобы в телеметрии не было информации, позволяющей идентифицировать личность.

Next.js;

Next.js 15.3 и более поздние версии (рекомендуется): инструментирование клиента (instrumentation-client.ts)

В Next.js 15.3 и более поздних версиях есть встроенные средства инструментирования на стороне клиента, которые используют файл instrumentation-client.ts (или instrumentation-client.js). Next.js выполняет этот файл в браузере до начала гидратации React.

Создайте файл src/instrumentation-client.ts (или instrumentation-client.ts в корневом каталоге проекта, если вы не используете каталог src/) и инициализируйте Crashlytics:

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

getCrashlytics(app);

Этот файл инициализирует Crashlytics до гидратации React и автоматически регистрирует глобальные прослушиватели ошибок (error и unhandledrejection) без изменений в src/app/layout.tsx или любом компоненте React.

Next.js < 15.3: клиентский (макет App Router)

В версиях Next.js до 15.3 layout.tsx по умолчанию является серверным компонентом. Поскольку FirebaseApp не сериализуется, оберните <FirebaseCrashlytics> (из @firebase/crashlytics/react, чтобы инициализировать Crashlytics и фиксировать неперехваченные ошибки) в клиентский компонент (например, src/components/CrashlyticsProvider.tsx), помеченный директивой '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}
    </>
  );
}

Затем оберните корневой макет в <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 (без React Router)

Оберните корневой компонент приложения (обычно src/App.tsx или src/main.tsx) компонентом <FirebaseCrashlytics>. Это глобальный приемник, который обрабатывает необработанные отклонения и исключения из браузера и пользовательского интерфейса React. Он охватывает все иерархии дочерних компонентов и автоматически фиксирует неперехваченные исключения или ошибки маршрутизации:

// 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 (версия 6 и выше)

Если вы используете React Router версии 6 или более поздней, замените контейнер <Routes> на <CrashlyticsRoutes>. Это позволяет автоматически сопоставлять границы ошибок на маршрутах и отслеживать ошибки, используя шаблонные названия путей, например /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

Если в вашем приложении используется TanStack Router, инициализируйте Crashlytics с помощью getCrashlytics(app) и прикрепите запись ошибок по умолчанию непосредственно в конфигурации экземпляра маршрутизатора (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);
  },
});

Примечание. Вызов getCrashlytics(app) автоматически регистрирует глобальные прослушиватели для неперехваченных ошибок окна и необработанных отклонений промисов, а defaultOnCatch фиксирует ошибки, перехваченные во время маршрутизации и отрисовки компонентов в TanStack Router.

(Необязательно) Шаг 4. Настройте управление версиями приложения

Настоятельно рекомендуем добавлять в сборки веб-приложений понятную строку версии, чтобы вы могли изолировать регрессии в определенных развертываниях. Передайте appVersion в CrashlyticsOptions при инициализации SDK Crashlytics для вашего фреймворка (используя строку выпуска или переменную среды времени сборки, например process.env.NEXT_PUBLIC_APP_VERSION или import.meta.env.VITE_APP_VERSION):

Angular

Передайте объект CrashlyticsOptions со значением appVersion в качестве второго аргумента в provideCrashlytics в 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 и более поздние версии (рекомендуется): инструментирование клиента (instrumentation-client.ts)

Передайте объект CrashlyticsOptions со свойством appVersion в качестве второго аргумента методу getCrashlytics в файле 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: клиентский (макет App Router)

Передайте crashlyticsOptions с appVersion в <FirebaseCrashlytics> в 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 (без React Router)

Передайте crashlyticsOptions с appVersion в <FirebaseCrashlytics> в 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 (версия 6 и выше)

Передайте crashlyticsOptions с appVersion в <CrashlyticsRoutes> в 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

Передайте объект CrashlyticsOptions с appVersion в качестве второго аргумента в 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);
  },
});

Шаг 5. Принудительно вызовите тестовый сбой

Чтобы завершить настройку Crashlytics и увидеть первые данные на панели управления Crashlytics в консоли Firebase, необходимо принудительно вызвать тестовый сбой.

1. Добавьте в приложение код, который можно использовать для принудительного тестового сбоя.

   Добавьте в приложение React, Next.js или Angular тестовую кнопку или триггер маршрута, который при нажатии вызывает ошибку выполнения:

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

   Если вы настроили автоматическую регистрацию ошибок с помощью <FirebaseCrashlytics> (React или Next.js), provideCrashlytics (Angular) или <CrashlyticsRoutes> (React Router), то при возникновении ошибки исключение будет автоматически зарегистрировано и запланировано к загрузке.

2. Скомпилируйте и запустите приложение, а затем вызовите тестовую ошибку, чтобы приложение отправило в Firebase первый отчет о сбое.

3. В консоли Firebase перейдите в раздел DevOps & Engagement (DevOps и взаимодействие) > Crashlytics dashboard (Панель управления) и проверьте, появился ли отчет о тестовом сбое.

   1. Выберите веб-приложение в раскрывающемся списке вверху страницы.

   2. Обновите страницу. Тестовое исключение должно появиться в таблице Проблемы в течение нескольких минут.

Если вы обновили консоль и по-прежнему не видите тестовый сбой через 5–10 минут, ознакомьтесь с разделом Устранение неполадок.

Crashlytics теперь отслеживает ошибки в вашем веб-приложении. Чтобы посмотреть и изучить все отчеты и статистику, перейдите на панель управления Crashlytics.

Дальнейшие действия

• Получайте понятные отчеты о сбоях. Настройте автоматическую загрузку файлов сопоставления (.js.map), чтобы в трассировках стека рабочей среды показывались исходные названия файлов и номера строк.
• Настройка отчетов о сбоях. Узнайте, как создавать отчеты об обработанных исключениях, добавлять специальные ключи, принудительно очищать записи телеметрии и настраивать выборку.