Mulai menggunakan Crashlytics untuk Web

Pilih platform:

iOS+ Android Android NDK Web Flutter Unity

Pratinjau: Crashlytics untuk aplikasi web adalah rilis pratinjau. Rilis pratinjau tidak tunduk pada SLA atau kebijakan penghentian layanan apa pun dan dapat berubah sehingga tidak kompatibel dengan versi sebelumnya.

Panduan ini menjelaskan cara mulai menggunakan Firebase Crashlytics di aplikasi web Anda.

Setelah menyiapkan Firebase Crashlytics SDK di aplikasi, Anda bisa mendapatkan laporan error yang komprehensif di Firebase console. Dengan Crashlytics untuk aplikasi web, Anda akan mendapatkan laporan terkait error.

Penting: Dukungan Crashlytics untuk aplikasi web akan diluncurkan dalam beberapa hari ke depan. Jika Anda belum melihat pengalaman ini di Firebase console, periksa kembali nanti.

Sebelum memulai

Penyiapan Crashlytics memerlukan tugas di Firebase console dan IDE Anda (seperti menambahkan konfigurasi Firebase aplikasi dan Crashlytics SDK). Untuk menyelesaikan penyiapan, paksa error pengujian agar Anda dapat mengirim laporan error pertama ke Firebase.

Untuk menyiapkan Crashlytics secara manual di aplikasi web, pastikan Anda telah menyelesaikan prasyarat berikut:

• Buat project Firebase dan aplikasi Firebase jika Anda belum memilikinya. Jika belum melakukannya, tambahkan Firebase ke project JavaScript Anda.

• Pastikan akun Anda memiliki izin Pemilik di project Anda. Hal ini diperlukan untuk mengaktifkan API dan peran IAM yang diperlukan.

• Pastikan project Firebase Anda menggunakan paket harga Blaze bayar sesuai penggunaan. Crashlytics untuk web menggunakan Cloud Logging untuk penyimpanan telemetri dan Cloud Storage untuk penyimpanan peta sumber, yang merupakan produk berbayar dengan tingkat tanpa biaya. Pelajari lebih lanjut harga Logging dan harga Cloud Storage.

Langkah 1: Mengaktifkan Crashlytics untuk aplikasi web Anda

Crashlytics untuk web menggunakan Cloud Logging, Error Reporting, dan Cloud Storage, sehingga Anda perlu mengaktifkan API ini dan mengonfigurasi izin untuk project Anda. Anda dapat mengaktifkan Crashlytics untuk aplikasi web menggunakan Firebase console atau Firebase CLI.

Menggunakan Firebase console

1. Di Firebase console, buka DevOps & Engagement > Crashlytics dashboard.

2. Pilih aplikasi web Anda dari pemilih drop-down di bagian atas halaman.

3. Klik Siapkan Crashlytics dan ikuti petunjuk di layar.

Menggunakan Firebase CLI

Penting: Meskipun dukungan Crashlytics untuk aplikasi web akan diluncurkan dalam beberapa hari ke depan, sebaiknya gunakan Firebase Firebase console untuk penyiapan. Jika Anda menggunakan Firebase CLI sekarang untuk menyiapkan Crashlytics, Anda mungkin tidak dapat melihat error di dasbor Crashlytics hingga akhir minggu ini.

Jika Anda lebih suka mengonfigurasi project dari terminal atau menggunakan agen coding AI, Anda dapat menggunakan Firebase CLI:

1. Pastikan Anda telah menginstal Firebase CLI v15.35.0 atau yang lebih baru dan telah diautentikasi (firebase login). Pelajari cara menginstal atau mengupdate Firebase CLI.

2. Jalankan perintah berikut untuk menyiapkan Crashlytics untuk aplikasi web Anda:

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

   Perintah ini melakukan langkah-langkah penyiapan berikut:

   • Memverifikasi bahwa project Anda menggunakan paket harga Blaze bayar sesuai penggunaan, dan meminta Anda untuk mengupgrade jika diperlukan.

   • Mengaktifkan API telemetri dan Crashlytics yang diperlukan (firebasetelemetry.googleapis.com, firebasetelemetryadmin.googleapis.com, firebasecrashlytics.googleapis.com, dan clienttelemetry.googleapis.com).

   • Jika kunci API aplikasi web Anda memiliki pembatasan API, tambahkan clienttelemetry.googleapis.com ke API yang diizinkan.

   • Mengonfigurasi setelan telemetri Crashlytics untuk aplikasi web Anda.

   • Saat dijalankan secara interaktif, perintah ini akan meminta Anda untuk mengaktifkan pemberitahuan email secara opsional untuk masalah baru dan masalah yang mengalami regresi.

Langkah 2: Tambahkan dan lakukan inisialisasi SDK di aplikasi Anda

1. Instal Crashlytics SDK:

   npm install firebase
   

2. Lakukan inisialisasi instance FirebaseApp Anda:

   Buat file utilitas konfigurasi pusat untuk menggunakan inisialisasi singleton. Untuk menemukan nilai konfigurasi aplikasi Firebase, buka halaman Setelan project > General di Firebase konsol, buka kartu Your apps, lalu pilih aplikasi web Anda.

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

Langkah 3: Konfigurasikan perekaman error otomatis untuk framework Anda

Penerima error framework otomatis dan pelacak manual menggunakan instance FirebaseApp bersama Anda. Pilih framework Anda untuk mengonfigurasi perekaman error otomatis:

Angular

Lakukan integrasi dengan runtime penangkapan error global Angular dan pelacakan rute otomatis dengan menambahkan provideCrashlytics(() => app) ke penyedia aplikasi Anda di 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)
  ]
};

Catatan: provideCrashlytics mendaftarkan ErrorHandler kustom untuk melacak error zona yang tidak tertangkap (Zone.js) dan menggunakan instance Router internal untuk membuat rute dinamis (seperti /dashboard/user/:id), bukan mencatat URL literal, sehingga telemetri bebas dari informasi identitas pribadi.

Next.js

Next.js 15.3+ (direkomendasikan): Instrumentasi klien (instrumentation-client.ts)

Next.js 15.3+ menyertakan instrumentasi sisi klien native melalui instrumentation-client.ts (atau instrumentation-client.js). Next.js mengeksekusi file ini di browser sebelum hidrasi React dimulai.

Buat src/instrumentation-client.ts (atau instrumentation-client.ts di root project Anda jika tidak menggunakan direktori src/) dan lakukan inisialisasi Crashlytics:

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

getCrashlytics(app);

File tunggal ini menginisialisasi Crashlytics sebelum hidrasi React dan secara otomatis mendaftarkan pemroses error global (error dan unhandledrejection) tanpa modifikasi pada src/app/layout.tsx atau komponen React apa pun.

Next.js < 15.3: Sisi klien (Tata letak Router Aplikasi)

Untuk Next.js versi sebelum 15.3, layout.tsx adalah Komponen Server secara default. Karena FirebaseApp tidak dapat diserialisasi, gabungkan <FirebaseCrashlytics> (dari @firebase/crashlytics/react untuk menginisialisasi Crashlytics dan menangkap error yang tidak tertangkap) dalam Komponen Klien (seperti src/components/CrashlyticsProvider.tsx) yang ditandai dengan perintah '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}
    </>
  );
}

Kemudian, gabungkan tata letak root Anda dengan <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 (tanpa React Router)

Gabungkan komponen aplikasi root Anda (biasanya src/App.tsx atau src/main.tsx) dengan komponen batas error <FirebaseCrashlytics>. Ini berfungsi sebagai penerima global, yang menangani penolakan dan pengecualian yang tidak tertangani dari browser dan UI React. Komponen ini menggabungkan semua hierarki komponen turunan dan secara otomatis menangkap pengecualian yang tidak tertangkap atau error pemilihan rute:

// 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+)

Jika Anda menggunakan React Router v6+, ganti penampung <Routes> React Router dengan <CrashlyticsRoutes>. Tindakan ini akan otomatis memetakan batas error di seluruh rute dan melacak error menggunakan nama jalur yang di-template, seperti /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

Jika aplikasi Anda menggunakan TanStack Router, lakukan inisialisasi Crashlytics dengan getCrashlytics(app) dan lampirkan perekaman error default langsung di dalam konfigurasi instance router Anda (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);
  },
});

Catatan: Memanggil getCrashlytics(app) akan otomatis mendaftarkan pemroses global untuk error jendela yang tidak tertangkap dan penolakan promise yang tidak ditangani, sedangkan defaultOnCatch menangkap error yang tertangkap selama pemilihan rute dan rendering komponen dalam TanStack Router.

(Opsional) Langkah 4: Siapkan pembuatan versi aplikasi

Sebaiknya tambahkan string versi yang jelas ke build aplikasi web Anda agar Anda dapat mengisolasi regresi ke deployment tertentu. Teruskan appVersion di CrashlyticsOptions saat melakukan inisialisasi Crashlytics SDK untuk framework Anda (menggunakan string rilis atau variabel lingkungan waktu build, seperti process.env.NEXT_PUBLIC_APP_VERSION atau import.meta.env.VITE_APP_VERSION):

Angular

Teruskan objek CrashlyticsOptions dengan appVersion sebagai argumen kedua ke provideCrashlytics di 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+ (direkomendasikan): Instrumentasi klien (instrumentation-client.ts)

Teruskan objek CrashlyticsOptions dengan appVersion sebagai argumen kedua ke getCrashlytics di 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: Sisi klien (Tata letak Router Aplikasi)

Teruskan crashlyticsOptions dengan appVersion ke <FirebaseCrashlytics> di 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 (tanpa React Router)

Teruskan crashlyticsOptions dengan appVersion ke <FirebaseCrashlytics> di 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+)

Teruskan crashlyticsOptions dengan appVersion ke <CrashlyticsRoutes> di 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

Teruskan objek CrashlyticsOptions dengan appVersion sebagai argumen kedua ke 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);
  },
});

Langkah 5: Paksa error pengujian

Untuk menyelesaikan penyiapan Crashlytics dan melihat data awal di dasbor Crashlytics pada Firebase console, Anda harus memaksa error pengujian.

1. Tambahkan kode ke aplikasi yang dapat Anda gunakan untuk memaksa error pengujian.

   Tambahkan tombol pengujian atau pemicu rute ke aplikasi React, Next.js, atau Angular Anda yang menampilkan error runtime saat diklik:

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

   Jika Anda mengonfigurasi pengambilan error otomatis dengan <FirebaseCrashlytics> (React atau Next.js), provideCrashlytics (Angular), atau <CrashlyticsRoutes> (React Router), menampilkan error ini akan otomatis mengambil pengecualian dan menjadwalkannya untuk diupload.

2. Build dan jalankan aplikasi Anda, lalu picu error pengujian agar aplikasi Anda mengirimkan laporan error pertamanya ke Firebase.

3. Di Firebase console, buka dasbor DevOps & Engagement > Crashlytics untuk memeriksa laporan error pengujian Anda:

   1. Pilih aplikasi web Anda dari pemilih drop-down di bagian atas halaman.

   2. Muat ulang halaman. Pengecualian pengujian Anda akan muncul di tabel Masalah dalam beberapa menit.

Jika Anda telah me-refresh konsol dan masih tidak melihat error pengujian setelah lima hingga sepuluh menit, lihat Memecahkan masalah penyiapan.

Crashlytics kini memantau aplikasi web Anda untuk menemukan error. Buka dasbor Crashlytics untuk melihat dan menyelidiki semua laporan dan statistik Anda.

Langkah berikutnya

• Dapatkan laporan error yang dapat dibaca: Siapkan upload peta sumber (.js.map) otomatis agar stack trace produksi Anda menampilkan nama file dan nomor baris asli.
• Menyesuaikan laporan error: Pelajari cara melaporkan pengecualian yang ditangani, menambahkan kunci kustom, memaksa penghapusan data telemetri, dan mengonfigurasi pengambilan sampel.