|---|---| | **Select platform:** | [iOS+](https://firebase.google.com/docs/crashlytics/ios/customize-crash-reports.md.txt) [Android](https://firebase.google.com/docs/crashlytics/android/customize-crash-reports.md.txt) [Web](https://firebase.google.com/docs/crashlytics/web/customize-crash-reports.md.txt) [Flutter](https://firebase.google.com/docs/crashlytics/flutter/customize-crash-reports.md.txt) [Unity](https://firebase.google.com/docs/crashlytics/unity/customize-crash-reports.md.txt) |
> [!WARNING] > **Preview:** Crashlytics for web apps is a **preview** release. A preview release is not subject to any SLA or deprecation policy and could change in backwards-incompatible ways. In the Firebase console (**DevOps \& Engagement** \> **[**Crashlytics** dashboard](https://console.firebase.google.com/project/_/crashlytics)**), you can click into an issue and get a detailed event report. You can customize those reports and manage your telemetry collection to help you better understand what is happening in your web app: - [Report handled exceptions programmatically](https://firebase.google.com/docs/crashlytics/web/customize-crash-reports.md.txt#log-excepts) - [Add custom keys](https://firebase.google.com/docs/crashlytics/web/customize-crash-reports.md.txt#add-keys) - [Force flush telemetry records for short-lived routines](https://firebase.google.com/docs/crashlytics/web/customize-crash-reports.md.txt#flush-telemetry-records) - [Configure sampling rate](https://firebase.google.com/docs/crashlytics/web/customize-crash-reports.md.txt#configure-sampling) - [Disable or enable telemetry collection](https://firebase.google.com/docs/crashlytics/web/customize-crash-reports.md.txt#disable-or-enable-telemetry) > [!IMPORTANT] > **Important:** Crashlytics support for web apps is rolling out over the next few days. If you don't yet see the experience in the Firebase console, check back soon! ## Report handled exceptions programmatically You can record handled exceptions manually using `recordError`. Routing errors and uncaught exceptions are captured automatically by your framework error boundaries. Here's how to track the failure prevalence and diagnostic attributes across your users: ```typescript 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); } } ``` ## Add custom keys Custom metadata keys help you understand the specific app state or user workflow leading up to a crash. You can log user activities, session states, and diagnostic details directly as key-value custom attributes using the optional metadata parameter when calling `recordError`: ```typescript 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' }); ``` These custom attributes are kept in the exception report and appear under the **Keys** tab in the [**Crashlytics** dashboard](https://console.firebase.google.com/project/_/crashlytics) issue view. ## Force flush telemetry records By default, the web telemetry engine batches logs into memory segments to preserve battery life, CPU performance, and network bandwidth. However, for short-lived execution environments, logs must be uploaded immediately before the execution context is destroyed. You can use the asynchronous `flush` command to send all queued errors to the backend immediately: ```typescript 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(); } ``` ## Configure sampling rate If you sample a proportion of your user sessions to control telemetry volume and cost, you can configure sampling using any of the following options: - **Option 1** *(recommended)* : [Configure sampling rate in the Firebase console](https://firebase.google.com/docs/crashlytics/web/customize-crash-reports.md.txt#configure-sampling-console) - **Option 2** : [Set sampling rate using the *Firebase Telemetry Admin API*](https://firebase.google.com/docs/crashlytics/web/customize-crash-reports.md.txt#configure-sampling-api) > [!NOTE] > **Note:** To configure sampling rate, you must have the **Owner** or **Editor** role on the Firebase project (or a custom IAM role with the `firebasetelemetryadmin.configs.list` and `firebasetelemetryadmin.configs.update` permissions). ### Option 1 *(recommended)* : Configure sampling rate in the Firebase console 1. In the Firebase console, go to the **DevOps \& Engagement** \> **[**Crashlytics** dashboard](https://console.firebase.google.com/project/_/crashlytics)**. 2. Select your web app from the drop-down selector at the top of the page. 3. Click **Configure sampling** in the top-right corner of the dashboard. 4. Set the **Sampling rate** percentage (between `0%` and `100%`) to control the percentage of events and sessions collected from clients. ### Option 2: Set sampling rate using the *Firebase Telemetry Admin API* You can use the *Firebase Telemetry Admin API* (`firebasetelemetryadmin.googleapis.com/v1alpha`) to manage telemetry collection settings for your Firebase apps.
1. Configure the following required variables in your terminal: ```bash 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. Find your CONFIG_NAME and then configure it as a variable in your terminal: Telemetry settings are managed using a `Config` resource, so you need to find the specific CONFIG_NAME for your web app. 1. List the configs in your project and filter by your FIREBASE_APP_ID. The `curl -G` and `--data-urlencode` flags ensure the AIP-160 filter string is correctly URL-encoded: ```bash 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. In the JSON response, locate the `name` field for your app (`projects/PROJECT_ID/locations/LOCATION/configs/`), and then set it as your `CONFIG_NAME` variable: ```bash CONFIG_NAME="CONFIG_NAME" ``` 3. Set the sampling rate: To adjust the sampling rate, use the `PATCH` method to update the `sampling_rate` field. You must specify `updateMask=sampling_rate` in the query parameters. The sampling rate is a double value representing the percentage of sessions to collect (for example, `0.25` for 25%): ```bash # 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" ``` ## Disable or enable telemetry collection By default, telemetry collection is enabled when you set up Crashlytics for your web app. If you need to disable or re-enable telemetry collection dynamically after installing the Crashlytics SDK, you can manage collection endpoints using the *Firebase Telemetry Admin API* (`firebasetelemetryadmin.googleapis.com/v1alpha`). > [!NOTE] > **Note:** To manage telemetry configuration resources, you must have the **Owner** or **Editor** role on the Firebase project (or a custom IAM role with the `firebasetelemetryadmin.configs.list` and `firebasetelemetryadmin.configs.update` permissions). Before you can disable or enable telemetry, you need to set the following variables:
1. Configure the following required variables in your terminal: ```bash 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. Find your CONFIG_NAME and then configure it as a variable in your terminal: Telemetry settings are managed using a `Config` resource, so you need to find the specific CONFIG_NAME for your web app. 1. List the configs in your project and filter by your FIREBASE_APP_ID. The `curl -G` and `--data-urlencode` flags ensure the AIP-160 filter string is correctly URL-encoded: ```bash 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. In the JSON response, locate the `name` field for your app (`projects/PROJECT_ID/locations/LOCATION/configs/`), and then set it as your `CONFIG_NAME` variable: ```bash CONFIG_NAME="CONFIG_NAME" ``` ### Disable telemetry collection Use the `:disable` custom method to disable telemetry collection: ```bash curl -X POST \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{}' \ "https://firebasetelemetryadmin.googleapis.com/v1alpha/${CONFIG_NAME}:disable" ``` ### Re-enable telemetry collection To re-enable telemetry collection, call the `:enable` method: ```bash curl -X POST \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{}' \ "https://firebasetelemetryadmin.googleapis.com/v1alpha/${CONFIG_NAME}:enable" ```