سفارشی‌سازی گزارش‌های خرابی برای وب

انتخاب پلاتفرم: iOS+ Android Web Flutter Unity


در کنسول Firebase (DevOps و تعامل > داشبورد Crashlytics)، می‌توانید روی مشکلی کلیک کنید و گزارش رویداد دقیقی دریافت کنید. می‌توانید این گزارش‌ها را سفارشی‌سازی کنید و مجموعه دورسنجی‌تان را مدیریت کنید تا به شما کمک کند آنچه را در برنامه وب شما اتفاق می‌افتد بهتر درک کنید:

گزارش کردن استثناهای رسیدگی‌شده به‌صورت برنامه‌نویسی‌شده

می‌توانید استثناهای رسیدگی‌شده را به‌صورت دستی بااستفاده از recordError ضبط کنید. خطاهای مسیریابی و استثناهای گرفته‌نشده به‌طور خودکار توسط مرزهای خطای چارچوب شما ضبط می‌شوند.

در اینجا نحوه ردیابی شیوع خرابی و مشخصه‌های عیب‌یابی در بین کاربران شما آورده شده است:

import { recordError, getCrashlytics } from '@firebase/crashlytics';
import { app } from './lib/firebase';

const crashlytics = getCrashlytics(app);

async function submitPaymentForm() {
  try {
    await api.processTransaction();
  } catch (error) {
    // Manually record handled exceptions with diagnostic context
    recordError(crashlytics, error, {
      userTier: 'Premium Gold',
      checkoutStage: 'BillingAddressVerification',
      transactionCode: 'tx_8412_err',
      retryAttempts: 2
    });
    showFallbackBanner(error);
  }
}

افزودن کلیدهای سفارشی

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

می‌توانید فعالیت‌های کاربر، وضعیت‌های جلسه، و جزئیات عیب‌یابی را مستقیماً به‌عنوان ویژگی‌های سفارشی مقدار کلید بااستفاده از پارامتر فراداده اختیاری هنگام فراخوانی recordError ثبت کنید:

import { recordError, getCrashlytics } from '@firebase/crashlytics';
import { app } from './lib/firebase'; // Shared initialization script

const crashlytics = getCrashlytics(app);

// Pass custom key-value diagnostic metadata within recordError
recordError(crashlytics, error, {
  userTier: 'Premium Gold',
  checkoutStage: 'BillingAddressVerification',
  transactionCode: 'tx_8412_err',
  retryAttempts: 2,
  breadcrumb: 'User opened shopping cart',
  lastAction: 'Click Checkout Button'
});

این مشخصه‌های سفارشی در گزارش استثنا نگهداری می‌شوند و در برگه کلیدها در نمای مشکل Crashlytics داشبورد ظاهر می‌شوند.

پاک‌سازی اجباری سوابق دورسنجی

به‌طور پیش‌فرض، موتور دورسنجی وب گزارش‌ها را در بخش‌های حافظه دسته‌بندی می‌کند تا عمر باتری، عملکرد واحد پردازش مرکزی، و پهنای باند شبکه را حفظ کند. بااین‌حال، برای محیط‌های اجرای کوتاه‌مدت، گزارش‌ها باید بلافاصله قبل‌از نابود شدن بافت اجرا بارگذاری شوند.

می‌توانید از فرمان ناهمگام flush برای ارسال فوری همه خطاهای صف‌بندی‌شده به باطن استفاده کنید:

import { recordError, flush, getCrashlytics } from '@firebase/crashlytics';
import { app } from './lib/firebase';

const crashlytics = getCrashlytics(app);

async function handleApplicationCrash(error: Error) {
  // Capture the error with immediate priority
  recordError(crashlytics, error, { priority: 'IMMEDIATE' });

  // Force an immediate upload before the process terminates or reloads
  await flush(crashlytics);

  // Safe to terminate or refresh the current execution context
  window.location.reload();
}

پیکربندی نرخ نمونه‌برداری

اگر برای کنترل حجم و هزینه دورسنجی، نسبتی از جلسه‌های کاربر را نمونه‌برداری می‌کنید، می‌توانید نمونه‌برداری را بااستفاده از هرکدام از گزینه‌های زیر پیکربندی کنید:

گزینه ۱ (توصیه‌شده): پیکربندی نرخ نمونه‌برداری در کنسول Firebase

  1. در کنسول Firebase، به داشبورد DevOps و تعامل > Crashlytics بروید.

  2. برنامه وب خود را از انتخابگر کرکره‌ای در بالای صفحه انتخاب کنید.

  3. روی پیکربندی نمونه‌گیری در گوشه بالا سمت راست داشبورد کلیک کنید.

  4. درصد نرخ نمونه‌برداری (بین 0% و 100%) را برای کنترل درصد رویدادها و جلسه‌های جمع‌آوری‌شده از کارخواه‌ها تنظیم کنید.

گزینه ۲: تنظیم کردن نرخ نمونه‌برداری بااستفاده از Firebase Telemetry Admin API

می‌توانید از Firebase Telemetry Admin API (firebasetelemetryadmin.googleapis.com/v1alpha) برای مدیریت تنظیمات جمع‌آوری دورسنجی برای برنامه‌های Firebase خود استفاده کنید.

  1. متغیرهای الزامی زیر را در پایانه خود پیکربندی کنید:

    PROJECT_ID="PROJECT_ID"
LOCATION="LOCATION"  # for example, global
APP_ID="FIREBASE_APP_ID"  # for example, 1:1234567890:web:abcdef123456
TOKEN=$(gcloud auth application-default print-access-token)

  2. CONFIG_NAME خود را پیدا کنید و سپس آن را به‌عنوان متغیر در پایانه خود پیکربندی کنید:

    تنظیمات دورسنجی بااستفاده از منبع Config مدیریت می‌شود، بنابراین باید CONFIG_NAME خاصی را برای برنامه وب خود پیدا کنید.

    1. می‌توانید فهرست پیکربندی‌های موجود در پروژه خود را ببینید و براساس FIREBASE_APP_ID فیلتر کنید. پرچم‌های curl -G و --data-urlencode تضمین می‌کنند که رشته فیلتر AIP-160 به‌درستی کدبندی نشانی وب شده است:

      curl -G \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "filter=app_id=\"${APP_ID}\"" \
  "https://firebasetelemetryadmin.googleapis.com/v1alpha/projects/${PROJECT_ID}/locations/${LOCATION}/configs"

    2. در پاسخ JSON، فیلد name را برای برنامه‌تان (projects/PROJECT_ID/locations/LOCATION/configs/<CONFIG_ID>) پیدا کنید، و سپس آن را به‌عنوان متغیر CONFIG_NAME تنظیم کنید:

      CONFIG_NAME="CONFIG_NAME"

  3. نرخ نمونه‌برداری را تنظیم کنید:

    برای تنظیم نرخ نمونه‌برداری، از روش PATCH برای به‌روزرسانی فیلد sampling_rate استفاده کنید. باید updateMask=sampling_rate را در پارامترهای پُرسمان مشخص کنید. نرخ نمونه‌برداری مقدار دوبرابری است که نشان‌دهنده درصد جلسه‌هایی است که باید جمع‌آوری شود (برای مثال، 0.25 برای ۲۵٪):

    # Example: Set sampling rate to 25%
curl -X PATCH \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{
    \"sampling_rate\": 0.25,
    \"app_id\": \"${APP_ID}\"
  }" \
  "https://firebasetelemetryadmin.googleapis.com/v1alpha/${CONFIG_NAME}?updateMask=sampling_rate"

غیرفعال یا فعال کردن جمع‌آوری دورسنجی

به‌طور پیش‌فرض، وقتی Crashlytics را برای برنامه وب خود راه‌اندازی می‌کنید، جمع‌آوری دورسنجی فعال می‌شود. اگر لازم است جمع‌آوری دورسنجی را به‌طور پویا پس‌از نصب کردن کیت توسعه نرم‌افزار Crashlytics غیرفعال یا دوباره فعال کنید، می‌توانید نقاط پایانی مجموعه را بااستفاده از Firebase Telemetry Admin API (firebasetelemetryadmin.googleapis.com/v1alpha) مدیریت کنید.

قبل‌از اینکه بتوانید دورسنجی را غیرفعال یا فعال کنید، باید متغیرهای زیر را تنظیم کنید:

  1. متغیرهای الزامی زیر را در پایانه خود پیکربندی کنید:

    PROJECT_ID="PROJECT_ID"
LOCATION="LOCATION"  # for example, global
APP_ID="FIREBASE_APP_ID"  # for example, 1:1234567890:web:abcdef123456
TOKEN=$(gcloud auth application-default print-access-token)

  2. CONFIG_NAME خود را پیدا کنید و سپس آن را به‌عنوان متغیر در پایانه خود پیکربندی کنید:

    تنظیمات دورسنجی بااستفاده از منبع Config مدیریت می‌شود، بنابراین باید CONFIG_NAME خاصی را برای برنامه وب خود پیدا کنید.

    1. می‌توانید فهرست پیکربندی‌های موجود در پروژه خود را ببینید و براساس FIREBASE_APP_ID فیلتر کنید. پرچم‌های curl -G و --data-urlencode تضمین می‌کنند که رشته فیلتر AIP-160 به‌درستی کدبندی نشانی وب شده است:

      curl -G \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "filter=app_id=\"${APP_ID}\"" \
  "https://firebasetelemetryadmin.googleapis.com/v1alpha/projects/${PROJECT_ID}/locations/${LOCATION}/configs"

    2. در پاسخ JSON، فیلد name را برای برنامه‌تان (projects/PROJECT_ID/locations/LOCATION/configs/<CONFIG_ID>) پیدا کنید، و سپس آن را به‌عنوان متغیر CONFIG_NAME تنظیم کنید:

      CONFIG_NAME="CONFIG_NAME"

غیرفعال کردن جمع‌آوری دورسنجی

از روش سفارشی :disable برای غیرفعال کردن جمع‌آوری دورسنجی استفاده کنید:

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}' \
  "https://firebasetelemetryadmin.googleapis.com/v1alpha/${CONFIG_NAME}:disable"

فعال کردن مجدد جمع‌آوری دورسنجی

برای فعال کردن مجدد جمع‌آوری دورسنجی، روش :enable را فراخوانی کنید:

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}' \
  "https://firebasetelemetryadmin.googleapis.com/v1alpha/${CONFIG_NAME}:enable"