تستخدم Google تكنولوجيا الذكاء الاصطناعي لترجمة المحتوى إلى لغتك المفضّلة، وقد تتضمّن بعض الأخطاء.

بدء استخدام 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 الخاص بك، في حال لم يسبق لك إجراء ذلك.
تأكَّد من أنّ حسابك لديه أذونات المالك في مشروعك. هذا الإجراء مطلوب لتفعيل واجهات برمجة التطبيقات وأدوار "إدارة الهوية وإمكانية الوصول" اللازمة.
تأكَّد من أنّ مشروعك على Firebase يستخدم خطة أسعار Blaze المَرِنة. يستخدم "Crashlytics" للويب "Cloud Logging" لتخزين بيانات القياس عن بُعد و"Cloud Storage" لتخزين خرائط المصدر، وهما منتجان مدفوعان يتوفّران بمستوى استخدام مجاني. مزيد من المعلومات حول أسعار Logging وأسعار Cloud Storage

الخطوة 1: تفعيل Crashlytics لتطبيق الويب

يستخدم "Crashlytics" للويب كلاً من "Cloud Logging" و"تقارير الأخطاء" و"Cloud Storage"، لذا عليك تفعيل واجهات برمجة التطبيقات هذه وضبط الأذونات لمشروعك. يمكنك تفعيل Crashlytics لتطبيق الويب باستخدام وحدة تحكّم Firebase أو واجهة سطر الأوامر (CLI) في Firebase.

استخدام وحدة تحكّم Firebase

في وحدة تحكّم Firebase، انتقِل إلى DevOps والتفاعل > لوحة بيانات Crashlytics.
اختَر تطبيق الويب من القائمة المنسدلة في أعلى الصفحة.
انقر على إعداد Crashlytics واتّبِع التعليمات الظاهرة على الشاشة.

استخدام واجهة سطر الأوامر (CLI) في Firebase

إذا كنت تفضّل ضبط مشروعك من الوحدة الطرفية أو باستخدام وكيل ترميز مستند إلى الذكاء الاصطناعي، يمكنك استخدام واجهة سطر الأوامر في Firebase:

تأكَّد من تثبيت الإصدار 15.35.0 من واجهة سطر الأوامر (CLI) في Firebase أو إصدار أحدث ومن مصادقة حسابك (firebase login). تعرَّف على كيفية تثبيت واجهة سطر الأوامر (CLI) في Firebase أو تحديثها.
نفِّذ الأمر التالي لإعداد 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 لتطبيق الويب.
- عند تشغيلها بشكل تفاعلي، ستطلب منك تفعيل التنبيهات عبر البريد الإلكتروني اختياريًا للمشاكل الجديدة والمشاكل التي تكرّرت.

الخطوة 2: إضافة حزمة تطوير البرامج (SDK) وإعدادها في تطبيقك

ثبِّت حزمة تطوير البرامج (SDK) لـ 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();

الخطوة 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

الإصدار 15.3 من Next.js والإصدارات الأحدث (يُنصح به): قياس أداء العميل (instrumentation-client.ts)

يتضمّن الإصدار 15.3 من Next.js والإصدارات الأحدث منه أدوات قياس أداء أصلية من جهة العميل من خلال 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 ويسجّل تلقائيًا مستمعي الأخطاء العامة (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 والإصدارات الأحدث)

إذا كنت تستخدم الإصدار 6 من React Router أو إصدارًا أحدث، استبدِل حاوية <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 كوسيطة ثانية إلى 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

الإصدار 15.3 من Next.js والإصدارات الأحدث (يُنصح به): قياس أداء العميل (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، عليك فرض تعطُّل اختباري.

أضِف رمزًا إلى تطبيقك يمكنك استخدامه لفرض تعطُّل تجريبي.

أضِف زر اختبار أو مشغّل مسار إلى تطبيق 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 & Engagement > لوحة بيانات Crashlytics للاطّلاع على تقرير الأعطال التجريبي:
1. اختَر تطبيق الويب من القائمة المنسدلة في أعلى الصفحة.
2. يُرجى إعادة تحميل الصفحة. من المفترض أن يظهر استثناء الاختبار في جدول المشاكل في غضون بضع دقائق.

إذا أعدت تحميل وحدة التحكّم وما زال عطل الاختبار لا يظهر بعد مرور خمس إلى عشر دقائق، يُرجى الاطّلاع على تحديد المشاكل وحلّها في عملية الإعداد.

يراقب Crashlytics الآن تطبيق الويب بحثًا عن الأخطاء. انتقِل إلى لوحة بيانات Crashlytics للاطّلاع على جميع التقارير والإحصاءات والتحقيق فيها.

الخطوات التالية

الحصول على تقارير أعطال قابلة للقراءة: يمكنك إعداد ميزة التحميل التلقائي لملفات خريطة المصدر (.js.map) لكي تعرض تتبعات تسلسل استدعاء الدوال البرمجية في الإصدار العلني أسماء الملفات وأرقام الأسطر الأصلية.
تخصيص تقارير الأعطال: تعرَّف على كيفية الإبلاغ عن الاستثناءات التي تم التعامل معها وإضافة مفاتيح مخصّصة وفرض تفريغ سجلات القياس عن بُعد وضبط أخذ العينات.

بدء استخدام Crashlytics للويب تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

قبل البدء

الخطوة 1: تفعيل Crashlytics لتطبيق الويب

استخدام وحدة تحكّم Firebase

استخدام واجهة سطر الأوامر (CLI) في Firebase

الخطوة 2: إضافة حزمة تطوير البرامج (SDK) وإعدادها في تطبيقك

الخطوة 3: ضبط ميزة "الالتقاط التلقائي للأخطاء" لإطار العمل

Angular

Next.js

React (بدون React Router)

React Router (الإصدار 6 والإصدارات الأحدث)

TanStack Router

(اختياري) الخطوة 4: إعداد إصدارات التطبيق

Angular

Next.js

React (بدون React Router)

React Router (الإصدار 6 والإصدارات الأحدث)

TanStack Router

الخطوة 5: فرض تعطُّل اختباري

الخطوات التالية

بدء استخدام Crashlytics للويب