Skip to content

Commit 85a66ed

Browse files
MichaelDoyleMichaelDoyle
authored
Crashlytics skills (#9776)
1 parent 5e1f0af commit 85a66ed

File tree

8 files changed

+803
-0
lines changed

8 files changed

+803
-0
lines changed

‎skills/firebase-crashlytics-basics/SKILL.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
---
2+
name: firebase-crashlytics-basics
3+
description: Comprehensive guide for Firebase Crashlytics, including SDK setup, instrumentation, and accessing crash reports. Use this skill when the user needs to instrument their mobile application, configure advanced reporting, or debug issues using crash data.
4+
compatibility: This skill is best used with the Firebase CLI, but does not require it. Install it by running `npm install -g firebase-tools`.
5+
---
6+
7+
# Firebase Crashlytics
8+
9+
This skill provides resources for integrating Firebase Crashlytics in Android applications and accessing crash reports.
10+
11+
## SDK Setup
12+
13+
To add Firebase Crashlytics to your application, follow the platform-specific guide:
14+
15+
* **Android**: [android_sdk.md](references/android_sdk.md)
16+
17+
## Instrumentation
18+
19+
Improve your crash reporting by adding advanced instrumentation:
20+
21+
* **Codebase Context**: [codebase_documentation.md](references/codebase_documentation.md)
22+
* **Analytics**: [instrument_analytics.md](references/instrument_analytics.md)
23+
* **Logging**: [instrument_logging.md](references/instrument_logging.md)
24+
25+
## Data & Reporting
26+
27+
Access crash reports and manage issues directly through the MCP server:
28+
29+
* **Reports**: [reports.md](references/reports.md)
30+
* **Issues**: [issues.md](references/issues.md)
31+
* **Investigations**: [investigations.md](references/investigations.md)

‎skills/firebase-crashlytics-basics/references/android_sdk.md‎

Lines changed: 199 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,199 @@
1+
# Adding Firebase Crashlytics to an Android App
2+
3+
This document provides a comprehensive guide for adding the Firebase Crashlytics SDK to an Android application, based on the latest official Firebase documentation.
4+
5+
## Step 1: Update your Gradle configuration
6+
7+
> **Note:** The following instructions are for projects using Gradle 8.0 or higher. If you are using an older version of Gradle, please refer to the official Firebase documentation for the appropriate setup.
8+
9+
### Project-level `settings.gradle.kts` (or `settings.gradle`)
10+
11+
In your project's root `settings.gradle.kts` or `settings.gradle` file, add the following to the `pluginManagement` block:
12+
13+
**Kotlin (`settings.gradle.kts`):**
14+
15+
```kotlin
16+
pluginManagement {
17+
repositories {
18+
google()
19+
mavenCentral()
20+
gradlePluginPortal()
21+
}
22+
plugins {
23+
id("com.android.application") version "8.4.1" apply false
24+
id("com.google.gms.google-services") version "4.4.2" apply false
25+
id("com.google.firebase.crashlytics") version "3.0.1" apply false
26+
}
27+
}
28+
```
29+
30+
**Groovy (`settings.gradle`):**
31+
32+
```groovy
33+
pluginManagement {
34+
repositories {
35+
google()
36+
mavenCentral()
37+
gradlePluginPortal()
38+
}
39+
plugins {
40+
id 'com.android.application' version '8.4.1' apply false
41+
id 'com.google.gms.google-services' version '4.4.2' apply false
42+
id 'com.google.firebase.crashlytics' version '3.0.1' apply false
43+
}
44+
}
45+
```
46+
47+
### App-level `build.gradle.kts` (or `build.gradle`)
48+
49+
In your app's `build.gradle.kts` or `build.gradle` file (usually located at `app/build.gradle`), apply the Crashlytics plugin and add the SDK dependencies.
50+
51+
**Kotlin (`build.gradle.kts`):**
52+
53+
```kotlin
54+
plugins {
55+
alias(libs.plugins.android.application)
56+
alias(libs.plugins.google.gms.google.services)
57+
alias(libs.plugins.google.firebase.crashlytics)
58+
}
59+
60+
dependencies {
61+
// Import the Firebase BoM
62+
implementation(platform("com.google.firebase:firebase-bom:33.1.2"))
63+
64+
// Add the dependency for the Firebase Crashlytics library
65+
// When using the BoM, you don't specify versions in Firebase library dependencies
66+
implementation("com.google.firebase:firebase-crashlytics-ktx")
67+
68+
// To get breadcrumb logs for crash reports, it's recommended to also add the Firebase Analytics dependency
69+
implementation("com.google.firebase:firebase-analytics-ktx")
70+
71+
// For apps with native code, it's recommended to also add the Crashlytics NDK dependency
72+
implementation("com.google.firebase:firebase-crashlytics-ndk")
73+
}
74+
75+
// If your app uses native code, configure the Crashlytics extension to upload native symbols.
76+
firebaseCrashlytics {
77+
// Enable processing and uploading of native symbols to Crashlytics.
78+
// This flag is disabled by default because it requires you to have the Android NDK installed.
79+
nativeSymbolUploadEnabled.set(true)
80+
81+
// Enable uploading of ProGuard/R8 mapping files
82+
// This is required for de-obfuscating stack traces if your app is minified.
83+
mappingFileUploadEnabled.set(true)
84+
}
85+
```
86+
87+
**Groovy (`build.gradle`):**
88+
89+
```groovy
90+
plugins {
91+
id 'com.android.application'
92+
id 'com.google.gms.google-services'
93+
id 'com.google.firebase.crashlytics'
94+
}
95+
96+
dependencies {
97+
// Import the Firebase BoM
98+
implementation platform('com.google.firebase:firebase-bom:33.1.2')
99+
100+
// Add the dependency for the Firebase Crashlytics library
101+
// When using the BoM, you don't specify versions in Firebase library dependencies
102+
implementation 'com.google.firebase:firebase-crashlytics-ktx'
103+
104+
// To get breadcrumb logs for crash reports, it's recommended to also add the Firebase Analytics dependency
105+
implementation 'com.google.firebase:firebase-analytics-ktx'
106+
107+
// For apps with native code, it's recommended to also add the Crashlytics NDK dependency
108+
implementation 'com.google.firebase:firebase-crashlytics-ndk'
109+
}
110+
111+
// If your app uses native code, configure the Crashlytics extension to upload native symbols.
112+
firebaseCrashlytics {
113+
// Enable processing and uploading of native symbols to Crashlytics.
114+
// This flag is disabled by default because it requires you to have the Android NDK installed.
115+
nativeSymbolUploadEnabled true
116+
117+
// Enable uploading of ProGuard/R8 mapping files
118+
// This is required for de-obfuscating stack traces if your app is minified.
119+
mappingFileUploadEnabled true
120+
}
121+
```
122+
123+
## Step 1.1: Troubleshooting Native Symbols
124+
125+
If you are using NDK and dont see symbolicated stack traces:
126+
127+
1. Ensure you have the **Android NDK** installed in Android Studio (SDK Manager > SDK Tools > NDK (Side by side)).
128+
2. Ensure `unstrippedNativeLibsDir` is pointing to the correct location if you are using a custom build system.
129+
3. Force a refresh of dependencies: `./gradlew clean app:assembleDebug --refresh-dependencies`.
130+
131+
## Step 1.2: Understanding ANRs
132+
133+
Crashlytics automatically captures ANR (Application Not Responding) events on Android 11+ devices.
134+
* **Requirement:** The app must be installed from the Google Play Store (or recognized by Play Services) for ANRs to be reported in many cases, though strictly local debugging often catches them too.
135+
* **No Extra Code:** You generally do not need extra code to enable ANR reporting with the latest SDKs.
136+
```
137+
138+
> **Note:** For the BoM and plugin versions, please refer to the official Firebase documentation for the latest versions.
139+
140+
## Step 2: Implement User Consent (Optional but Recommended)
141+
142+
It is a best practice to allow users to opt-out of crash reporting. You can control data collection by enabling or disabling it programmatically.
143+
144+
In your `Application` class or main activity, you can add the following code:
145+
146+
```java
147+
import com.google.firebase.crashlytics.FirebaseCrashlytics;
148+
149+
// ...
150+
151+
// Check for user's preference and enable/disable collection accordingly
152+
FirebaseCrashlytics.getInstance().setCrashlyticsCollectionEnabled(userHasOptedIn);
153+
```
154+
155+
You can also do this in your `AndroidManifest.xml` by adding `<meta-data android:name="firebase_crashlytics_collection_enabled" android:value="false" />` inside the `<application>` tag. The programmatic approach is more flexible as it allows you to change the setting at runtime.
156+
157+
## Step 3: Using Crashlytics
158+
159+
Once initialized, Crashlytics will automatically report crashes. You can also use it to log custom events and non-fatal exceptions.
160+
161+
### Log Custom Messages
162+
163+
```java
164+
FirebaseCrashlytics.getInstance().log("User performed a custom action");
165+
```
166+
167+
### Record Non-Fatal Exceptions
168+
169+
```java
170+
try {
171+
// ...
172+
} catch (Exception e) {
173+
FirebaseCrashlytics.getInstance().recordException(e);
174+
}
175+
```
176+
177+
### Set User Identifiers
178+
179+
```java
180+
FirebaseCrashlytics.getInstance().setUserId("user123");
181+
```
182+
183+
### Set Custom Keys
184+
185+
```java
186+
FirebaseCrashlytics.getInstance().setCustomKey("level", "5");
187+
FirebaseCrashlytics.getInstance().setCustomKey("score", "10000");
188+
```
189+
190+
## Step 4: Final Steps
191+
192+
1. Sync your project with the Gradle files.
193+
2. Run your app to verify the implementation.
194+
3. To test your implementation, you can force a test crash:
195+
```java
196+
throw new RuntimeException("Test Crash"); // Force a crash
197+
```
198+
4. After the app crashes, run it again so the Crashlytics SDK can upload the report.
199+
5. Check the Firebase Crashlytics dashboard to see the crash report.

‎skills/firebase-crashlytics-basics/references/codebase_documentation.md‎

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
# The Agent's Guide to "Technical Reference" Codebase Documentation
2+
3+
## 1. Introduction
4+
5+
**The goal is to create a definitive technical reference for the application.**
6+
7+
When a developer (or an agent) enters a codebase, they don't just need to know "what" the app does; they need to know exactly how it implements its features. Your goal is to create a "maximalist" document that is a comprehensive, living specification of the application's internals. It should be robust enough that a developer could implement a new feature (like "Add a new field to the User Profile") almost entirely by consulting this document, without needing to spend hours reverse-engineering the existing patterns.
8+
9+
## 2. Core Principles of Technical Documentation
10+
11+
1. **Aim for Density:** A high-quality reference for an Android app should be **1000+ lines** or equivalent density depending on the complexity of the app. Do not verify your work until you have achieved significant depth.
12+
2. **Exhaustive, Not Exemplary:**
13+
- _Bad:_ "The app has many actions, such as `ACTION_SYNC`."
14+
- _Good:_ A complete Markdown Table listing **every single** Action constant, event type, or API endpoint, and what it does.
15+
3. **Tables are Power:** Use tables for Schemas, Intent Actions, URI Matchers, and API Endpoints. They are scannable and authoritative.
16+
4. **Architectural Narratives:** Don't just list components. Explain the _patterns_ (e.g., "The MVVM Pattern", "The Repository Pattern", "The Offline-First Sync Loop").
17+
5. **Preserve the User Narrative:** Start with _what_ the user does, but immediately pivot to _how_ the code executes it.
18+
19+
## 3. The Step-by-Step "Technical Reference" Process
20+
21+
### Step 1: Broad Reconnaissance & Architecture Identification
22+
23+
Before writing, understand the "Skeleton" of the app.
24+
25+
- **Identify the Core Pattern:** Is it MVVM? MVP? Clean Architecture? A legacy Service-Oriented pattern?
26+
- **Find the "Big Layers":**
27+
1. **The Logic/Network Layer:** Who handles the heavy lifting? (e.g., `NetworkManager`, `Repository`, `ApiService`).
28+
2. **The Data Store:** Who manages persistence? (e.g., `RoomDatabase`, `ContentProvider`, `Realm`).
29+
3. **The UI Entry Points:** Where does the User Interface start? (e.g., `MainActivity`, `HomeFragment`).
30+
31+
### Step 2: Extracting "the Standard Model"
32+
33+
Create precise references for the application's data and network layers.
34+
35+
- **Data Layout:** Open the core Model classes (e.g., `User.java`, `Item.kt`). Extract the **Schema**.
36+
- _Output:_ A table of every column/field, its type, and its purpose.
37+
- **Network Protocol:** Open the API definition or Network Service. Extract the **API**.
38+
- _Output:_ A table of every endpoint, command, or action constant available to the app.
39+
- **Routing/Navigation:** If special routing is used (Deep Links, Navigation Graph), map every route.
40+
41+
### Step 3: Deep Dives into Core Flows
42+
43+
Select the top 3-5 most complex features and document their implementation flow step-by-step.
44+
45+
- **Synchronization:** How does data move between Local DB and Server? (Detail conflict resolution, retry policies, offline states).
46+
- **Authentication:** Exact auth flow (e.g., OAuth -> Token Exchange -> Session Storage).
47+
- **Complex Feature X:** The unique "Secret Sauce" of the application (e.g., Video Processing, Bluetooth constraints).
48+
49+
### Step 4: The "How-To" Development Guide
50+
51+
Anticipate the reader's next task. Write a "Cookbook" section.
52+
53+
- **"How to Add a New Field":** Walk through the 5-6 files typically touched to add a single property to a model. (Migration -> Model -> Parser -> UI).
54+
- **"How to Debug":** Where are the logs? What tags to filter? Key breakpoints?
55+
56+
## 4. Structure of a Technical Reference Document
57+
58+
Use this template structure for your `TECHNICAL_REFERENCE.md`:
59+
60+
```markdown
61+
# TECHNICAL REFERENCE: [App Name]
62+
63+
## 1. Core Architecture
64+
65+
[Deep dive into the architectural pattern. Explain "The Logic", "The Store", "The Face".]
66+
67+
## 2. Network Layer Reference
68+
69+
### 2.1 Strategy
70+
71+
[Libraries used: Retrofit/OkHttp/Ktor, JSON parsing strategy, Threading model.]
72+
73+
### 2.2 API / Action Reference (Complete List)
74+
75+
| Constant / Route | Value | Purpose |
76+
| :--------------------------------------------- | :----- | :------------------------------------- |
77+
| ACTION_SYNC | "sync" | Triggers the bi-directional sync loop. |
78+
| ... (List ALL available actions/endpoints) ... | ... | ... |
79+
80+
## 3. Data Layer Reference
81+
82+
### 3.1 Schema & ORM
83+
84+
[Explain the ORM pattern, e.g., "Room", "Active Record", "Raw SQLite".]
85+
86+
#### Table: [table_name]
87+
88+
| Column | Type | Description |
89+
| :------------------------- | :------ | :---------------- |
90+
| id | INTEGER | Local Primary Key |
91+
| remote_id | STRING | Server ID |
92+
| ... (List ALL columns) ... | ... | ... |
93+
94+
## 4. Feature Implementation Details
95+
96+
### 4.1 Feature 1
97+
98+
[Step-by-step logic ...]
99+
100+
### 4.2 Feature 2
101+
102+
[Details ...]
103+
```
104+
105+
## 5. Final Quality Check
106+
107+
Before submitting:
108+
109+
1. **Did I filter or condense too much?** If you summarized a list of 50 items down to "various actions", **GO BACK**. The user wants the list.
110+
2. **Is it code-grounded?** Every section should cite specific filenames and class names.
111+
3. **Is it authoritative?** Does this look like an official spec written by the lead engineer?
112+
113+
By following this guide, you ensure that `TECHNICAL_REFERENCE.md` serves its true purpose: **Empowering developers to master the codebase instantly.**

0 commit comments

Comments
 (0)