เริ่มต้นใช้งาน Crashlytics สำหรับเว็บ

เลือกแพลตฟอร์ม iOS+ Android Android NDK เว็บ Flutter Unity


คู่มือนี้จะอธิบายวิธีเริ่มต้นใช้งาน Firebase Crashlytics ในเว็บแอป

หลังจากตั้งค่า SDK ของ Firebase Crashlytics ในแอปแล้ว คุณจะได้รับรายงานข้อขัดข้องที่ครอบคลุมในคอนโซล Firebase เมื่อใช้ Crashlytics สำหรับเว็บแอป คุณจะได้รับรายงานข้อผิดพลาด

ก่อนเริ่มต้น

การตั้งค่า Crashlytics ต้องดำเนินการทั้งในคอนโซล Firebase และ IDE (เช่น การเพิ่มการกำหนดค่า Firebase ของแอปและ SDK ของ Crashlytics) หากต้องการตั้งค่าให้เสร็จสมบูรณ์ คุณจะต้องบังคับให้เกิดข้อขัดข้องเพื่อทดสอบการส่งรายงานข้อขัดข้องฉบับแรกไปยัง Firebase

หากต้องการตั้งค่า Crashlytics ในเว็บแอปด้วยตนเอง โปรดตรวจสอบว่าคุณได้ทำตามข้อกำหนดเบื้องต้นต่อไปนี้แล้ว

  • สร้างโปรเจ็กต์ Firebase และแอป 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 CLI

ใช้คอนโซล Firebase

  1. ในคอนโซล Firebase ให้ไปที่ DevOps และการมีส่วนร่วม > แดชบอร์ด Crashlytics

  2. เลือกเว็บแอปจากตัวเลือกแบบเลื่อนลงที่ด้านบนของหน้า

  3. คลิกตั้งค่า Crashlytics แล้วทำตามวิธีการบนหน้าจอ

ใช้ Firebase CLI

หากต้องการกำหนดค่าโปรเจ็กต์จากเทอร์มินัลหรือใช้เอเจนต์การเขียนโค้ด AI คุณสามารถใช้ Firebase CLI ได้โดยทำดังนี้

  1. ตรวจสอบว่าคุณได้ติดตั้ง Firebase CLI v15.35.0 ขึ้นไปและได้รับการตรวจสอบสิทธิ์แล้ว (firebase login) ดูวิธีติดตั้งหรืออัปเดต Firebase CLI

  2. เรียกใช้คำสั่งต่อไปนี้เพื่อตั้งค่า Crashlytics สำหรับเว็บแอปของคุณ

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

    คำสั่งนี้จะดำเนินการตามขั้นตอนการตั้งค่าต่อไปนี้

    • ยืนยันว่าโปรเจ็กต์ใช้แพ็กเกจราคา Blaze แบบจ่ายเมื่อใช้ และแจ้งให้คุณอัปเกรดหากจำเป็น

    • เปิดใช้ Crashlytics และ API การตรวจวัดระยะไกลที่จำเป็น (firebasetelemetry.googleapis.com, firebasetelemetryadmin.googleapis.com, firebasecrashlytics.googleapis.com และ clienttelemetry.googleapis.com)

    • หากคีย์ API ของเว็บแอปมีข้อจำกัด API ให้เพิ่ม clienttelemetry.googleapis.com ลงใน API ที่อนุญาต

    • กำหนดการตั้งค่าการตรวจวัดระยะไกลของ Crashlytics สำหรับเว็บแอป

    • เมื่อเรียกใช้แบบอินเทอร์แอกทีฟ ระบบจะแจ้งให้คุณเปิดใช้การแจ้งเตือนทางอีเมลสำหรับปัญหาใหม่และปัญหาที่เกิดซ้ำ (ไม่บังคับ)

ขั้นตอนที่ 2: เพิ่มและเริ่มต้น SDK ในแอป

  1. ติดตั้ง Crashlytics SDK:

    npm install firebase

  2. เริ่มต้นอินสแตนซ์ FirebaseApp โดยทำดังนี้

    สร้างไฟล์ยูทิลิตีการกำหนดค่าส่วนกลางเพื่อใช้การเริ่มต้น Singleton หากต้องการดูค่าการกำหนดค่าแอป Firebase ให้ไปที่หน้า การตั้งค่าโปรเจ็กต์ > ทั่วไปในคอนโซล Firebase ไปที่การ์ดแอปของคุณ แล้วเลือกเว็บแอป

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

ผสานรวมกับรันไทม์การตรวจจับข้อผิดพลาดส่วนกลางของ 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)
  ]
};

Next.js

Next.js 15.3 ขึ้นไป (แนะนำ): การใช้เครื่องมือฝั่งไคลเอ็นต์ (instrumentation-client.ts)

Next.js 15.3 ขึ้นไปมีการวัดฝั่งไคลเอ็นต์แบบเนทีฟผ่าน instrumentation-client.ts (หรือ instrumentation-client.js) โดย Next.js จะเรียกใช้ไฟล์นี้ในเบราว์เซอร์ก่อนที่ React Hydration จะเริ่มขึ้น

สร้าง 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 Hydration และลงทะเบียน Listener ข้อผิดพลาดส่วนกลาง (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 UI โดยจะรวมลำดับชั้นคอมโพเนนต์ย่อยทั้งหมดและบันทึกข้อยกเว้นที่ไม่ได้ตรวจจับหรือข้อผิดพลาดในการกำหนดเส้นทางโดยอัตโนมัติ

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

หากคุณใช้ React Router v6 ขึ้นไป ให้แทนที่คอนเทนเนอร์ <Routes> ของ React Router ด้วย <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);
  },
});

(ไม่บังคับ) ขั้นตอนที่ 4: ตั้งค่าการกำหนดเวอร์ชันของแอป

เราขอแนะนำอย่างยิ่งให้เพิ่มสตริงเวอร์ชันที่ชัดเจนลงในบิลด์ของเว็บแอป เพื่อให้คุณแยกการถดถอยไปยังการติดตั้งใช้งานที่เฉพาะเจาะจงได้ ส่ง appVersion ใน CrashlyticsOptions เมื่อเริ่มต้น SDK Crashlytics สำหรับเฟรมเวิร์กของคุณ (โดยใช้สตริงรุ่นหรือตัวแปรสภาพแวดล้อมเวลาบิลด์ เช่น process.env.NEXT_PUBLIC_APP_VERSION หรือ import.meta.env.VITE_APP_VERSION)

Angular

ส่งออบเจ็กต์ CrashlyticsOptions ที่มี appVersion เป็นอาร์กิวเมนต์ที่ 2 ไปยัง 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 เป็นอาร์กิวเมนต์ที่ 2 ไปยัง 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 (v6+)

ส่ง 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 เป็นอาร์กิวเมนต์ที่ 2 ไปยัง 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 และการมีส่วนร่วม > แดชบอร์ด Crashlytics เพื่อตรวจสอบรายงานข้อขัดข้องทดสอบ โดยทำดังนี้

    1. เลือกเว็บแอปจากตัวเลือกแบบเลื่อนลงที่ด้านบนของหน้า

    2. รีเฟรชหน้าเว็บ ข้อยกเว้นการทดสอบควรปรากฏในตารางปัญหาภายในไม่กี่นาที

หากรีเฟรชคอนโซลแล้วและยังไม่เห็นข้อขัดข้องจากการทดสอบหลังจากผ่านไป 5-10 นาที โปรดดูการแก้ปัญหาการตั้งค่า


ตอนนี้ Crashlytics กำลังตรวจสอบข้อผิดพลาดในเว็บแอปของคุณ ไปที่แดชบอร์ด Crashlytics เพื่อดูและตรวจสอบรายงานและสถิติทั้งหมด

ขั้นตอนถัดไป

  • รับรายงานข้อขัดข้องที่อ่านได้: ตั้งค่าการอัปโหลดแผนที่แหล่งที่มา (.js.map) อัตโนมัติเพื่อให้สแต็กเทรซเวอร์ชันที่ใช้งานจริงแสดงชื่อไฟล์และหมายเลขบรรทัดต้นฉบับ
  • ปรับแต่งรายงานข้อขัดข้อง: ดูวิธีรายงานข้อยกเว้นที่จัดการ เพิ่มคีย์ที่กำหนดเอง บังคับล้างบันทึกการวัดและส่งข้อมูลทางไกล และกำหนดค่าการสุ่มตัวอย่าง