Turning Rork App Crash Reports You Can Actually Read — Field Notes on dSYM Recovery, Context Logs, and Staged Distribution

Android: always send the R8 mapping from CI

On Android, release builds run R8 to shrink and obfuscate code. Enable the Crashlytics Gradle plugin in android/app/build.gradle and the mapping file upload kicks in automatically.

plugins {
  id 'com.android.application'
  id 'com.google.gms.google-services'
  id 'com.google.firebase.crashlytics'
}
 
android {
  buildTypes {
    release {
      // If you obfuscate, uploading the mapping is mandatory
      minifyEnabled true
      firebaseCrashlytics {
        mappingFileUploadEnabled true
        nativeSymbolUploadEnabled true   // when you ship NDK code
      }
    }
  }
}

Leave mappingFileUploadEnabled off while obfuscation is on and your Android traces go uniformly unreadable. Turn obfuscation off and you no longer need the mapping, but the app becomes easier to reverse-engineer — so in production I prefer to build on the assumption that the mapping is always sent.

Give every crash its preceding context

Once symbolication works, you know where it crashed. What actually eats your time is how it got there. This is where custom keys and breadcrumbs pay off: send the app state at the moment of the crash together with the trail of actions that led to it.

import crashlytics from "@react-native-firebase/crashlytics";
 
// Keep the latest app state attached as keys
export function setCrashContext(state: {
  screen: string;
  userTier: "free" | "pro";
  networkType: string;
}) {
  crashlytics().setAttributes({
    screen: state.screen,
    userTier: state.userTier,
    network: state.networkType,
  });
}
 
// Leave a trail of important actions (attached chronologically on a crash)
export function trace(action: string) {
  crashlytics().log(`[${new Date().toISOString()}] ${action}`);
}

Call setCrashContext on every screen transition, and wrap "expensive to get wrong" operations like billing and API calls with trace before and after. Now the crash detail in Crashlytics shows a state like "Pro user / checkout screen / offline" alongside a trail of "checkout started → token fetch failed." The time spent guessing repro conditions drops dramatically.

Non-fatal errors deserve recording too. Sending exceptions you swallow in try/catch — failures the user never sees but that quietly degrade quality — through recordError makes that hidden decay visible.

try {
  await syncPurchases();
} catch (e) {
  // Record without crashing
  crashlytics().recordError(e as Error, "purchase-sync-failed");
}

One caution here: never put personal or sensitive data such as email addresses or billing tokens into keys or logs. Keep context at the level of "categories of state" and never send raw values. Designing it that way saves you a great deal of trouble if an audit is ever needed.

Staged distribution gated on crash-free rate

Once reports are readable, the next job is to keep a bad build from spreading. App Distribution lets you split recipients into groups, so ship first to an internal group (yourself plus a few testers), confirm the crash-free rate clears your bar, and only then promote to the wider tester group. Build this into GitHub Actions.

name: distribute
on:
  push:
    branches: [main]
 
jobs:
  build-and-distribute:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
 
      - name: Build (EAS)
        run: npx eas-cli build --platform android --profile preview --non-interactive --no-wait
 
      - name: Distribute to internal group first
        run: |
          firebase appdistribution:distribute "$APP_PATH" \
            --app "$FIREBASE_APP_ID" \
            --groups "internal" \
            --release-notes "$(git log -1 --pretty=%s)"
        env:
          FIREBASE_TOKEN: ${{ secrets.FIREBASE_TOKEN }}

Promotion to the wider group is safest as a separate job behind a manual approval (required reviewers on an environment). The crash-free rate still has limited automation APIs, so I run promotion on the condition of "24 hours of internal distribution with no new crashes." Rather than rushing toward full automation, leaving one gate to a human has, in practice, reduced incidents.

The FIREBASE_TOKEN can expire. If CI suddenly stops with an "authentication error," suspect an expired token first. Leaning on a service-account approach (GOOGLE_APPLICATION_CREDENTIALS) keeps you from being jerked around by that expiry.

Crash-free rate as an operational metric

The crash-free rate is the share of your users who did not experience a crash. The bar I aim for is 99.5% or higher by users, and 99.9% on critical screens such as launch and checkout. Half a percent sounds tiny, but in an app used by ten thousand people that means someone is crashing nearly every day.

Staring at the number changes nothing. Once a week I look only at the top three crashes and knock them out one at a time, ordered by how many users they affect. This habit of "continuously shaving only the top issues" is, for the limited hours of solo development, the highest-leverage routine I have found. Trying to chase every crash burns you out, so I deliberately cap it at three.

I have been building apps on my own since 2014, and I still run wallpaper and relaxation apps today. What hit home around the time AdMob revenue began to climb steadily was that watching whether already-shipped apps were quietly breaking mattered more to long-term revenue than new development did. Instrumenting crash monitoring with context, and guarding distribution with a gate, is not flashy — but it is the foundation that lets one person carry several apps that run far away from my desk.

Your next step

Start by deliberately triggering a crash in a local release build and confirming that the Crashlytics trace shows function names rather than symbols. Only once that reads correctly do context logs and staged distribution start to mean anything. Verifying that the map arrived is where everything begins.

If you are likewise watching several apps on your own, I hope this helps. Thank you for reading.