Issues & Crashes

The Capture SDK can automatically detect, capture, and upload issues and errors that affect your app.

See the Product > Issues Feature Guide to learn more about how to navigate this information in the product.

Setup

Fatal issue reporting is enabled by default in the Capture SDK since 0.18.7 version but can be disabled as shown below.

Disable Issue Reporting

If you wish to disable automatic fatal issue reporting, you can set enableFatalIssueReporting = false in Configuration Logger.start().

Android (Kotlin)Android (Java)iOS (Swift)iOS (Objective-C)React Native

Kotlin

Logger.start(
  apiKey = "<your-api-key>",
  sessionStrategy = SessionStrategy.Fixed,
  configuration = Configuration(enableFatalIssueReporting = false),
)

Java

boolean enableFatalIssueReporting = false;
Logger.start(
  new Configuration(
      new SessionReplayConfiguration(),
      new SessionStrategy.Fixed(),
      enableFatalIssueReporting);
);

Swift

Logger.start(
  withAPIKey: "<your-api-key>",
  sessionStrategy: .fixed(),
  configuration: Capture.Configuration(enableFatalIssueReporting: false),
)

Objective-C

#import <Capture/Capture.h>

CAPConfiguration *config = [[CAPConfiguration alloc]
  initWithEnableFatalIssueReporting:NO
  enableURLSessionIntegration:YES];

[CAPLogger
  startWithAPIKey:@"your-api-key"
  sessionStrategy: [CAPSessionStrategy fixed]
  configuration:config];

Note

Issue reports on iOS are uploaded only for actual devices and not simulators

JavaScript

import { init, SessionStrategy } from '@bitdrift/react-native';

init('<api-key>', SessionStrategy.Activity, {
  crashReporting: {
    enableNativeFatalIssues: false,
  }
});

React Native JavaScript Support

The React Native SDK supports capturing global JavaScript errors in addition to platform crashes. This feature is experimental and can be enabled via the UNSTABLE_enableJsErrors configuration flag.

Supported Configuration

JavaScript error reporting is currently supported on Expo builds using the New Architecture and Hermes engine.

Configuration

JavaScript

import { init, SessionStrategy } from '@bitdrift/react-native';

init('<api-key>', SessionStrategy.Activity, {
  crashReporting: {
    enableNativeFatalIssues: true,
    UNSTABLE_enableJsErrors: true,
  }
});

• enableNativeFatalIssues: When true, enables reporting of native issues including crashes, ANRs (Application Not Responding), and other critical errors. Defaults to true.
• UNSTABLE_enableJsErrors: When true, enables reporting of JavaScript errors via React Native's global error handler. Captures unhandled exceptions with stack traces. Defaults to false.

Experimental

The UNSTABLE_enableJsErrors flag is experimental. This feature is under active development and may change in future releases.

Behavior

First Install Launch

Crash detection will not be enabled on fresh installations or after clearing app data/cache to allow remote configuration control. You may need to relaunch the app once for crash reporting to become active.

Session Uploads

Fatal issue reports and their session information (logs, etc) are automatically uploaded and do not require a Record Session to be running in a Workflow.

Android

Platform Support

• ANR detection is supported on Android 11+ (API level 30 or higher).
• Native (NDK) crash detection requires Android 12+ (API level 31 or higher)

R8/ProGuard Settings

To preserve line numbers and source file names for stack traces, make sure this rule is added to your app's ProGuard configuration:

-keepattributes SourceFile,LineNumberTable

Note

• SourceFile: This attribute is kept by default since Android Gradle Plugin (AGP) 8.2, and only needs to be explicitly kept in apps using earlier versions of AGP.
• LineNumberTable: This attribute is kept by default since Android Gradle Plugin (AGP) 8.6, and only needs to be explicitly kept in apps using earlier versions of AGP.

iOS

Platform Support

• Fatal issue reports are uploaded only for physical devices and not simulators.

Uploading Debug Information Files

To generate human readable stack traces, bitdrift needs your apps' debug information files.

bd cli tool

Our command-line tool makes it easy to upload debug information files to bitdrift.

Installation

Homebrew (macOS)

To install the CLI directly on your Mac, use Homebrew:

Bash

brew tap bitdriftlabs/bd
brew install bd

Direct Download

Direct downloads for other platforms are also available, which are especially useful for integrating into your CI or release process. You can download the latest binaries directly from:

macOS (Universal)macOS (arm64)macOS (x86_64)Linux (x86_64)

https://dl.bitdrift.io/bd-cli/latest/bd-cli-mac-universal-apple-darwin.tar.gz/bd

https://dl.bitdrift.io/bd-cli/latest/bd-cli-mac-arm64.tar.gz/bd

https://dl.bitdrift.io/bd-cli/latest/bd-cli-mac-x86_64.tar.gz/bd

https://dl.bitdrift.io/bd-cli/latest/bd-cli-linux-x86_64.tar.gz/bd

Info

You can download a specific version of the bd-cli by replacen latest above with the version number, e.g. 0.1.36

Usage

Proguard Mappings (Android)Native Symbols (iOS / Android)Sourcemaps (React Native)

Bash

bd debug-files upload-proguard
  --api-key <API_KEY>
  --app-id <APP_ID>
  --app-version <APP_VERSION>
  --version-code <VERSION_CODE>
  <PROGUARD_MAPPING_FILE>

Bash

bd debug-files upload
  --api-key <API_KEY>
  <FILE_OR_DIRECTORY> # MACH-O, ELF

Bash

bd debug-files upload-source-map \
  --source-map <SOURCEMAP_FILE> \
  --bundle <BUNDLE_FILE> \
  --api-key <API_KEY>

Example:

Bash

bd debug-files upload-source-map \
  --source-map ./android/app/build/generated/sourcemaps/react/release/index.android.bundle.map \
  --bundle ./android/app/build/generated/assets/createBundleReleaseJsAndAssets/index.android.bundle \
  --api-key $BD_API_KEY

Note

For BYOC deployments use --base-domain to target your deployment.

Platform Tools

Bitdrift supports build-time integration to upload the required Debug Information Files easily.

Gradle Plugin (Android)

Debug information files (proguard mappings, native symbols) can be located and uploaded via the Capture Gradle Plugin.

Info

The following requires the usage of the Capture Gradle Plugin, learn how to configure it in Android Quickstart Guide.

After a project sync, the Capture Gradle Plugin will automatically generate the bdUpload+ gradle tasks under the Upload group. You can then call them after succesfully assembling a release build (via assembleRelease):

• bdUploadMapping - Locate and upload only mapping files to Bitdrift
• bdUploadSymbols - Locate and upload only symbols to Bitdrift
• bdUploadSourceMap - Locate and upload only sourcemap files to Bitdrift
• bdUpload - Locate and upload all mapping files, symbols, and sourcemaps to Bitdrift (when applicable)

You must set an ENV variable named API_KEY to call these tasks

e.g.

Bash

API_KEY=MY-API-KEY ./gradlew bdUploadMapping

or:

Bash

export API_KEY=MY-API-KEY
./gradlew bdUploadMapping

Xcode Build Phase Script (iOS)

In the "Build Phases" tab of your Xcode build target, add a run script phase (click the "+" symbol in the top-left, then select "New Run Script Phase"), and use the following script:

Build Script

Bash

########################################
# Configuration
########################################

UPLOAD_ON_CONFIGURATIONS=(
    # Debug
    Release
)

########################################
# Script
########################################

set -eu -o pipefail

if [[ ! " ${UPLOAD_ON_CONFIGURATIONS[*]} " =~ [[:space:]]${CONFIGURATION}[[:space:]] ]]; then
    echo "This build step is not configured to upload symbols when using build configuration \"$CONFIGURATION\", so doing nothing."
    exit 0
fi

if [[ "$(uname -m)" == arm64 ]]; then
    BD_ARCH=arm64
else
    BD_ARCH=x86_64
fi
BD_URL="https://dl.bitdrift.io/bd-cli/latest/bd-cli-mac-${BD_ARCH}.tar.gz/bd"
BD="$TEMP_DIR/bd"

dsym_files=()
if [ $ENABLE_USER_SCRIPT_SANDBOXING == "YES" ]; then
    if [ $SCRIPT_INPUT_FILE_COUNT -le 0 ]; then
        echo 'ENABLE_USER_SCRIPT_SANDBOXING is enabled. All dSYMs must be declared in the "Input Files" section of this run script when sandboxing is enabled.'
        echo 'Please either disable ENABLE_USER_SCRIPT_SANDBOXING, or add the following into the "Input Files" section of this run script:'
        echo '    ${DWARF_DSYM_FOLDER_PATH}/${DWARF_DSYM_FILE_NAME}/Contents/Resources/DWARF/${TARGET_NAME}'
        exit 1
    fi

    for ((n=0;n<$SCRIPT_INPUT_FILE_COUNT;n++)); do
        declare name=SCRIPT_INPUT_FILE_${n}
        if [ -f "${!name}" ]; then
            dsym_files+=("${!name}")
        fi
    done
else
    dsym_files+=("${DWARF_DSYM_FOLDER_PATH}")
fi

if [ ${#dsym_files[@]} -eq 0 ]; then
    echo "Did not find any dSYM files to upload to Bitdrift. By default, Debug builds don't include dSYM files."
    echo "If you want to generate dSYM files in a debug build, modify your 'Debug Information Format' build setting and set it to 'DWARF with dSYM File'."
    exit 0
fi

if [ -z ${API_KEY+x} ]; then
    echo "Bitdrift requires the 'API_KEY' environment value to be set."
    echo "Please set API_KEY to your Bitdrift API key value, then launch xcode or xcodebuild from that environment."
    exit 1
fi

if [ ! -f "$BD" ]; then
    curl -fSL "$BD_URL" -o "$BD"
    curl -fSL "$BD_URL.sha256" -o "$BD.sha256" || {
        echo "ERROR: Failed to download bd-cli checksum from $BD_URL.sha256"
        rm -f "$BD"
        exit 1
    }

    EXPECTED_CHECKSUM=$(cat "$BD.sha256")
    ACTUAL_CHECKSUM=$(shasum -a 256 "$BD" | awk '{print $1}')

    if [ "$EXPECTED_CHECKSUM" != "$ACTUAL_CHECKSUM" ]; then
        echo "ERROR: Checksum verification failed for bd-cli binary"
        echo "Expected: $EXPECTED_CHECKSUM"
        echo "Actual:   $ACTUAL_CHECKSUM"
        rm -f "$BD" "$BD.sha256"
        exit 1
    fi

    chmod a+x "$BD"
    rm -f "$BD.sha256"
fi

for path in "${dsym_files[@]}"; do
    echo "Uploading to Bitdrift: $path"
    "$BD" debug-files upload --api-key="$API_KEY" "$path"
done

Info

You will need to set the API_KEY environment variable to your Bitdrift API key, and run your build under that environment

Info

If you have script sandboxing enabled on your build, you'll need to expose the symbol files so that the script can see them. This can be done by adding an entry with ${DWARF_DSYM_FOLDER_PATH}/${DWARF_DSYM_FILE_NAME}/Contents/Resources/DWARF/${TARGET_NAME} to the "Input Files" section of the run script build phase.

Note

For BYOC deployments use --base-domain to target your deployment.

---

Leave Feedback

Name (Optional):

Feedback:

Cancel Submit Feedback