Crash reports

Bugsee automatically intercepts uncaught exceptions and sends crash reports on app restart. Refer to installation for more details. However, due to various optimizations, stack traces in these reports can be mangled. To make them human readable and point to correct code locations Bugsee requires additional debug information which should be collected and sent as described in this section.

Symbolication

Native

To symbolicate crashes captured in native code, you should configure underlying Android and iOS projects following the instructions in the documentation for these SDKs. Refer to symbolication documentation for Android and iOS.

JavaScript

We rely on sourcemaps to fill captured stack traces with proper methods, filenames and line numbers. To let this magic happen, Bugsee needs the related sourcemaps which is uploaded automatically once you configure your projects following instructions below.

By default, during Bugsee initialization, we will try to get version automatically. Similarly, during build we will pick the application version from underlying native projects. If versions in Android/iOS projects and the one obtained during the initialization are in sync, then no extra actions are required. If not (e.g. when you set version explicitly following instructions below), then you should provide Bugsee with correct version using Bugsee.setAppVersion('<your_app_version>') method.

Sourcemaps: Automatic upload

Prerequisites

Before proceeding with automatic upload configuration, you need to ensure you have bugsee-sourcemaps tool installed. It's included as development dependency of Bugsee React Native SDK and thus may not be installed by default.

You can install it globally or locally. In either case, source maps collection scripts will locate it properly.

!Local installation

# with NPM
npm install --save-dev bugsee-sourcemaps

# with Yarn
yarn add bugsee-sourcemaps --dev

!Global installation

# with NPM
npm install -g bugsee-sourcemaps

# with Yarn
yarn global add bugsee-sourcemaps

Android

Open your application build script (usually located in <$PROJECT_DIR>/android/app/build.gradle) and add the line shown in the code snippet below

// this line should be in the file
apply from: "../../node_modules/react-native/react.gradle"

// add the line below
apply from: "../../node_modules/react-native-bugsee/bugsee.gradle"

After Gradle integration is set up, you need to provide configuration options to let Bugsee React Native SDK perform correctly. These options can be specified in several ways (these are listed in a order in which properties are being read):

  • Dedicated options file
  • Options in gradle script
  • Environment variables

!Dedicated options file

// create properties file <$PROJECT_DIR>/android/bugsee.properties with the following

app.version=1.0.001
app.token=<your-app-token>

!Options in Gradle script

// add the following to <$PROJECT_DIR>/android/app/build.gradle

project.ext.bugseeConfig = [
    appVersion: "1.0.001",
    appToken: "<your-app-token>"
]

!Environment variables

# Specify the following options

export BUGSEE_APP_TOKEN="<your-app-token>"
export BUGSEE_APP_VERSION="1.0.001"

Note that providing the application token is mandatory, whereas application version can be extracted automatically if not provided. Also, you can specify different properties in different sources, i.e. you can set application token in dedicated properties file and application version in the environment variable.

Bugsee React Native SDK also supports dedicated bugsee.properties files for different flavors. For that, you need to be using to add:

project.ext.bugseeConfig = [
    flavorAware: true
]

In this case, your properties file for the "Android staging" flavor would be <$PROJECT-DIR>/android/bugsee-staging.properties.

iOS

Open XCode and navigate to Build Phases in your project. Locate the "Bundle React Native code and images" phase and change its code from this

export NODE_BINARY=node
../node_modules/react-native/scripts/react-native-xcode.sh

to this

!React Native pre-0.69

export NODE_BINARY=node
# this is a relative path to the file with configuration options. Optional.
export BUGSEE_PROPERTIES=./bugsee.properties

../node_modules/react-native-bugsee/scripts/build-wrap.sh ../node_modules/react-native/scripts/react-native-xcode.sh

!React Native 0.69+

export NODE_BINARY=node
# this is a relative path to the file with configuration options. Optional.
export BUGSEE_PROPERTIES=./bugsee.properties

WITH_ENVIRONMENT="../node_modules/react-native/scripts/xcode/with-environment.sh"
REACT_NATIVE_XCODE="../node_modules/react-native/scripts/react-native-xcode.sh"
BUGSEE_SCRIPT="../node_modules/react-native-bugsee/scripts/build-wrap.sh"

/bin/sh -c "$BUGSEE_SCRIPT $WITH_ENVIRONMENT $REACT_NATIVE_XCODE"

In the code snippet above, we set an additional environment varialble "BUGSEE_PROPERTIES" which is pointing to the file with configuration options. It's optional, which means you can omit it. But, in this case you will have to specify the configuration options as environment variables here in the script. Please see examples below.

!Dedicated options file

// create properties file <$PROJECT_DIR>/ios/bugsee.properties with the following

app.version=1.0.001
app.token=<your-app-token>

!Environment variables

# Specify the following options

export BUGSEE_APP_TOKEN="<your-app-token>"
export BUGSEE_APP_VERSION="1.0.001"

Note that providing the application token is mandatory, whereas application version can be extracted automatically if not provided.

Sourcemaps: Manual upload

To upload sourcemaps manually, you will need bugsee-sourcemaps tool.

By default, sourcemaps are generated by react-native CLI tool but you need to call it yourself to generate them. You will also need to trigger upload command for bugsee-sourcemaps to upload generated data. To simplify this process we provide make command which does all those steps for you. Below, we briefly describe the steps and give you command examples on how to upload sourcemaps in your generic development flow.

Debug builds

  • Open your React Native project
  • Make some changes
  • Build
  • Upload sourcemaps with:

!iOS

# Execute in project root or add project path as last parameter
bugsee-sourcemaps make -t <YOUR-TOKEN> \
-v <APP-VERSION> \
-p ios \
-c debug \
--overwrite

!Android

# Execute in project root or add project path as last parameter
bugsee-sourcemaps make -t <YOUR-TOKEN> \
-v <APP-VERSION> \
-p android \
-c debug \
--overwrite
  • Run your app

Release builds

IMPORTANT: For release builds, we strongly recommend to upload sourcemaps BEFORE deploying your app. That will guarantee your reports will not fail to symbolicate due to missing symbols.

  • Open your React Native project
  • Make some changes
  • Build
  • Upload sourcemaps with:

!iOS

# Execute in project root or add project path as last parameter
bugsee-sourcemaps make -t <YOUR-TOKEN> \
-v <APP-VERSION> \
-p ios \
-c release \
--overwrite

!Android

# Execute in project root or add project path as last parameter
bugsee-sourcemaps make -t <YOUR-TOKEN> \
-v <APP-VERSION> \
-p android \
-c release \
--overwrite
  • Deploy your build app to target Store