‫Google برای ترجمه محتوا به زبان ترجیحی شما از فناوری هوشواره استفاده می‌کند. ترجمه‌های هوشواره‌ای ممکن است اشتباه داشته باشند.

شروع به کار با Crashlytics برای وب

انتخاب پلاتفرم:

iOS+ Android Android NDK Web Flutter Unity

این راهنما نحوه شروع به کار با Firebase Crashlytics را در برنامه وب شما شرح می‌دهد.

پس‌از راه‌اندازی کیت توسعه نرم‌افزار Firebase Crashlytics در برنامه‌تان، می‌توانید گزارش‌های خرابی جامع را در کنسول Firebase دریافت کنید. با Crashlytics برای برنامه‌های وب، گزارش‌های خطا را دریافت می‌کنید.

قبل از شروع

راه‌اندازی Crashlytics نیازمند انجام کارهایی هم در کنسول Firebase و هم در محیط توسعه یکپارچه شما است (مثل افزودن پیکربندی Firebase برنامه‌تان و کیت توسعه نرم‌افزار Crashlytics). برای تکمیل راه‌اندازی، باید خرابی آزمایشی را اجباری کنید تا اولین گزارش خرابی به Firebase ارسال شود.

برای راه‌اندازی دستی Crashlytics در برنامه وب، مطمئن شوید پیش‌نیازهای زیر را تکمیل کرده‌اید:

اگر پروژه Firebase و برنامه Firebase ندارید، آن‌ها را ایجاد کنید. اگر قبلاً این کار را نکرده‌اید، Firebase را به پروژه JavaScript خود اضافه کنید.
مطمئن شوید حسابتان اجازه‌های مالک را در پروژه‌تان داشته باشد. این برای فعال کردن میاناهای برنامه‌سازی کاربردی و نقش‌های IAM ضروری لازم است.
مطمئن شوید پروژه Firebase شما در طرح قیمت‌گذاری Blaze پرداخت به اندازه استفاده باشد. Crashlytics برای وب از Cloud Logging برای فضای ذخیره‌سازی دورسنجی و Cloud Storage برای فضای ذخیره‌سازی نقشه منبع استفاده می‌کند که محصولات پولی با سطح رایگان هستند. درباره قیمت‌گذاری Logging و قیمت‌گذاری Cloud Storage بیشتر بدانید.

مرحله ۱: Crashlytics را برای برنامه وب خود فعال کنید

Crashlytics برای وب از Cloud Logging، «گزارش خطا»، و Cloud Storage استفاده می‌کند، بنابراین باید این میاناهای برنامه‌سازی کاربردی را فعال کنید و اجازه‌های پروژه‌تان را پیکربندی کنید. می‌توانید Crashlytics را برای برنامه وب خود بااستفاده از کنسول Firebase یا CLI Firebase فعال کنید.

استفاده از کنسول Firebase

در کنسول Firebase، به DevOps و تعامل > داشبورد Crashlytics بروید.
برنامه وب خود را از انتخابگر کرکره‌ای در بالای صفحه انتخاب کنید.
روی راه‌اندازی Crashlytics کلیک کنید و دستورالعمل‌های روی صفحه را دنبال کنید.

استفاده از Firebase CLI

اگر ترجیح می‌دهید پروژه‌تان را از پایانه پیکربندی کنید یا از عامل کدنویسی هوش مصنوعی استفاده کنید، می‌توانید از Firebase CLI استفاده کنید:

مطمئن شوید که Firebase CLI نسخه ۱۵.۳۵.۰ یا بالاتر را نصب کرده‌اید و اصالت‌سنجی شده‌اید (firebase login). با نحوه نصب یا به‌روزرسانی Firebase CLI آشنا شوید.
فرمان زیر را برای راه‌اندازی Crashlytics برای برنامه وب خود اجرا کنید:
```
firebase crashlytics:setup \
  --app FIREBASE_APP_ID \
  --project PROJECT_ID
```
این فرمان مراحل راه‌اندازی زیر را انجام می‌دهد:
- درستی‌سنجی می‌کند که پروژه‌تان در طرح قیمت‌گذاری Blaze پرداخت به اندازه استفاده باشد و درصورت نیاز، از شما می‌خواهد ارتقا دهید.
- Crashlytics و میاناهای برنامه‌سازی کاربردی دورسنجی لازم را فعال می‌کند (firebasetelemetry.googleapis.com، firebasetelemetryadmin.googleapis.com، firebasecrashlytics.googleapis.com، و clienttelemetry.googleapis.com).
- اگر کلید میانای برنامه‌سازی کاربردی برنامه وب شما محدودیت‌های میانای برنامه‌سازی کاربردی دارد، clienttelemetry.googleapis.com را به میاناهای برنامه‌سازی کاربردی مجاز آن اضافه می‌کند.
- تنظیمات دورسنجی Crashlytics را برای برنامه وب شما پیکربندی می‌کند.
- وقتی به‌صورت تعاملی اجرا می‌شود، از شما می‌خواهد که به‌طور اختیاری هشدارهای ایمیلی را برای مشکلات جدید و پس‌رفت‌کرده فعال کنید.

مرحله ۲: افزودن و مقداردهی اولیه کیت توسعه نرم‌افزار در برنامه

کیت توسعه نرم‌افزار Crashlytics را نصب کنید:
```
npm install firebase
```

نمونه FirebaseApp خود را مقداردهی اولیه کنید:

یک فایل ابزار پیکربندی مرکزی ایجاد کنید تا از مقداردهی اولیه سینگلتون استفاده کنید. برای پیدا کردن مقادیر پیکربندی برنامه 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();

مرحله ۳: پیکربندی ضبط خودکار خطا برای چارچوب شما

هم گیرنده‌های خطای چارچوب خودکار و هم ردیاب‌های دستی از نمونه FirebaseApp هم‌رسانی‌شده شما استفاده می‌کنند. چارچوبتان را برای پیکربندی ضبط خودکار خطا انتخاب کنید:

Angular

با افزودن provideCrashlytics(() => app) به ارائه‌دهندگان برنامه‌تان در src/app/app.config.ts، با زمان اجرای Angular برای گرفتن خطای سراسری و ردیابی خودکار مسیر ادغام کنید:

// 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 در مرورگر اجرا می‌کند.

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 مقداردهی اولیه می‌کند و به‌طور خودکار شنوندگان خطای سراسری (error و unhandledrejection) را بدون هیچ تغییری در src/app/layout.tsx یا هر مؤلفه React دیگری ثبت می‌کند.

Next.js < 15.3: سمت کارخواه (چیدمان مسیریاب برنامه)

برای نسخه‌های Next.js قدیمی‌تر از ۱۵.۳، 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);
  },
});

(اختیاری) مرحله ۴: راه‌اندازی نسخه‌بندی برنامه

افزودن رشته نسخه واضح به ساخت‌های برنامه وب شما به‌شدت توصیه می‌شود تا بتوانید رگرسیون‌ها را به استقرارهای خاص جدا کنید. appVersion را در CrashlyticsOptions هنگام مقداردهی اولیه کیت توسعه نرم‌افزار 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: سمت کارخواه (چیدمان مسیریاب برنامه)

مجوز 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 به‌عنوان آرگومان دوم به 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);
  },
});

مرحله ۵: اجبار به ازکارافتادن آزمایشی

برای تکمیل راه‌اندازی Crashlytics و دیدن داده‌های اولیه در داشبورد Crashlytics در کنسول Firebase، باید یک خرابی آزمایشی را اجباری کنید.

کدی را به برنامه‌تان اضافه کنید که بتوانید از آن برای ایجاد خرابی آزمایشی استفاده کنید.

دکمه آزمایشی یا راه‌انداز مسیر را به برنامه 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) پیکربندی کرده باشید، با ایجاد این خطا، استثنا به‌طور خودکار ضبط می‌شود و برای بارگذاری زمان‌بندی می‌شود.
برنامه‌تان را بسازید و اجرا کنید، سپس خطای آزمایشی را راه‌اندازی کنید تا برنامه‌تان اولین گزارش خرابی را به Firebase ارسال کند.
در کنسول Firebase، به داشبورد DevOps و تعامل > Crashlytics بروید تا گزارش خرابی آزمایشی را بررسی کنید:
1. برنامه وب خود را از انتخابگر کرکره‌ای در بالای صفحه انتخاب کنید.
2. صفحه را بازخوانی کنید. استثنای آزمایشی شما باید ظرف چند دقیقه در جدول مشکلات نشان داده شود.

اگر کنسول را بازآوری کرده‌اید و هنوز خرابی آزمایشی را پس‌از پنج تا ده دقیقه نمی‌بینید، به عیب‌یابی راه‌اندازی مراجعه کنید.

Crashlytics اکنون برنامه وب شما را برای یافتن خطاها پایش می‌کند. برای مشاهده و بررسی همه گزارش‌ها و آمار، به داشبورد Crashlytics بروید.

مراحل بعدی

دریافت گزارش‌های خرابی خوانا: بارگذاری خودکار نقشه منبع (.js.map) را راه‌اندازی کنید تا ردیابی‌های پشته تولید شما نام فایل‌ها و شماره خطوط اصلی را نمایش دهد.
سفارشی‌سازی گزارش‌های خرابی: با نحوه گزارش کردن استثناهای رسیدگی‌شده، افزودن کلیدهای سفارشی، پاک‌سازی اجباری سوابق دورسنجی، و پیکربندی نمونه‌گیری آشنا شوید.

شروع به کار با Crashlytics برای وب با مجموعه‌ها، منظم بمانید ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.

قبل از شروع

مرحله ۱: Crashlytics را برای برنامه وب خود فعال کنید

استفاده از کنسول Firebase

استفاده از Firebase CLI

مرحله ۲: افزودن و مقداردهی اولیه کیت توسعه نرم‌افزار در برنامه

مرحله ۳: پیکربندی ضبط خودکار خطا برای چارچوب شما

Angular

Next.js

React (بدون React Router)

React Router (v6+)

TanStack Router

(اختیاری) مرحله ۴: راه‌اندازی نسخه‌بندی برنامه

Angular

Next.js

React (بدون React Router)

React Router (v6+)

TanStack Router

مرحله ۵: اجبار به ازکارافتادن آزمایشی

مراحل بعدی

شروع به کار با Crashlytics برای وب