BugSplat

Crash and error reporting built for busy developers.

Introduction 👋

The bugsplat-android library enables posting native crash reports to BugSplat from Android devices. Visit bugsplat.com for more information and to sign up for an account.

Requirements 📋

• Android Gradle Plugin (AGP): 8.5.1 or higher (for 16KB page size support)
• Android NDK: r27 or higher recommended
• minSdkVersion: 21 or higher
• targetSdkVersion: 35 or higher recommended

16KB Page Size Support

Starting November 1st, 2025, Google Play requires all new apps and updates targeting Android 15+ to support 16 KB page sizes. The BugSplat Android SDK is built with 16KB ELF alignment to comply with this requirement.

To ensure your app is 16KB compatible:

1. Use AGP 8.5.1 or higher
2. Use useLegacyPackaging false in your packagingOptions (this enables proper 16KB zip alignment)
3. If you have your own native code, ensure it's compiled with 16KB ELF alignment

Integration 🏗️

BugSplat supports multiple methods for installing the bugsplat-android library in a project.

Gradle (Recommended)

Add the BugSplat dependency to your app's build.gradle file:

dependencies {
    implementation 'com.bugsplat:bugsplat-android:1.3.0'
}

BugSplat is hosted on Maven Central, which is included by default in most Android projects. If needed, ensure mavenCentral() is in your settings.gradle.kts:

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
    }
}

Manual Setup

To integrate BugSplat into your Android application using the AAR file:

1. Download the AAR file

   • Go to the Releases page of the BugSplat Android repository
   • Download the latest bugsplat-android-x.y.z.aar file (where x.y.z is the version number)

2. Add the AAR to your project

   • Create a libs directory in your app module if it doesn't already exist
   • Copy the downloaded AAR file into the libs directory

3. Configure your app's build.gradle file

   • Open your app-level build.gradle file
   • Add the following to the dependencies section:

   dependencies {
       // Other dependencies...
       implementation files('libs/bugsplat-android-x.y.z.aar') // Replace x.y.z with the actual version
   }

4. Add the required permissions

   • Open your AndroidManifest.xml file
   • Add the following permissions:

   <uses-permission android:name="android.permission.INTERNET" />
   <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

5. Sync your project

   • Click "Sync Now" in the notification that appears, or select "Sync Project with Gradle Files" from the File menu

After completing these steps, you can start using BugSplat in your Android application. See the Usage section below for details on how to initialize and configure BugSplat.

Usage 🧑‍💻

Configuration

To configure BugSplat to handle native crashes, simply call BugSplat.init with the desired arguments. Be sure that the value you provide for database matches the value in the BugSplat web app.

BugSplat.init(this, database, application, version)

Loading config from local.properties (recommended)

Keeping your database name, app name, and version in one place avoids drift between runtime (BugSplat.init) and symbol upload. The pattern most BugSplat users adopt:

1. Add the database name to the gitignored local.properties:

   bugsplat.database=your_database

2. In your app module's build.gradle, load it and expose it (plus applicationId and versionName) as BuildConfig fields:

   def localProps = new Properties()
   def localPropsFile = rootProject.file('local.properties')
   if (localPropsFile.exists()) {
       localPropsFile.withInputStream { localProps.load(it) }
   }
   
   android {
       defaultConfig {
           applicationId "com.example.myapp"
           versionName "1.0.0"
   
           buildConfigField "String", "BUGSPLAT_DATABASE",
               "\"${localProps.getProperty('bugsplat.database')}\""
           buildConfigField "String", "BUGSPLAT_APP_NAME",
               "\"${applicationId}\""
           buildConfigField "String", "BUGSPLAT_APP_VERSION",
               "\"${versionName}\""
       }
       buildFeatures { buildConfig true }
   }

3. Initialize BugSplat from the generated BuildConfig:

   BugSplat.init(
       this,
       BuildConfig.BUGSPLAT_DATABASE,
       BuildConfig.BUGSPLAT_APP_NAME,
       BuildConfig.BUGSPLAT_APP_VERSION
   );

See example/build.gradle for the complete working setup. This same bugsplat.database value is also picked up by the symbol upload task, so there's a single source of truth across the whole build.

Attributes and attachments

You can also add custom attributes and/or file attachments to your crash reports.

Kotlin

val attributes = mapOf(
    "key1" to "value1",
    "key2" to "value2",
    "environment" to "development"
)

val attachmentPath = applicationContext.getFileStreamPath("log.txt").absolutePath
val attachments = arrayOf(attachmentPath)

BugSplat.init(
    this,
    BuildConfig.BUGSPLAT_DATABASE,
    BuildConfig.BUGSPLAT_APP_NAME,
    BuildConfig.BUGSPLAT_APP_VERSION,
    attributes,
    attachments
)

Java

Map<String, String> attributes = new HashMap<>();
attributes.put("key1", "value1");
attributes.put("environment", "development");

String attachmentPath = getApplicationContext().getFileStreamPath("log.txt").getAbsolutePath();
String[] attachments = new String[]{attachmentPath};

BugSplat.init(
    this,
    BuildConfig.BUGSPLAT_DATABASE,
    BuildConfig.BUGSPLAT_APP_NAME,
    BuildConfig.BUGSPLAT_APP_VERSION,
    attributes,
    attachments
);

Symbol Upload

To symbolicate crash reports, you must upload your app's .so files to the BugSplat backend. The BugSplat Android SDK provides two ways to upload symbols:

1. Using the Built-in Symbol Uploader

The BugSplat Android SDK includes a built-in symbol uploader that can be used to upload symbols programmatically:

// Upload symbols asynchronously
BugSplat.uploadSymbols(context, "YourDatabase", "YourApp", "1.0.0", nativeLibsDir);

// Or with client credentials (recommended for production)
BugSplat.uploadSymbols(context, "YourDatabase", "YourApp", "1.0.0", 
                      "your_client_id", "your_client_secret", nativeLibsDir);

// Or upload symbols synchronously (blocking)
try {
    BugSplat.uploadSymbolsBlocking(context, "YourDatabase", "YourApp", "1.0.0", nativeLibsDir);
    
    // Or with client credentials
    BugSplat.uploadSymbolsBlocking(context, "YourDatabase", "YourApp", "1.0.0",
                                  "your_client_id", "your_client_secret", nativeLibsDir);
} catch (IOException e) {
    Log.e("YourApp", "Failed to upload symbols", e);
}

This approach requires the symbol-upload executable to be included in your app's assets directory. See the Example App README for more details on how to set this up.

2. Using Gradle Build Tasks

You can wire symbol upload into your Gradle build so it runs automatically after assembleDebug / assembleRelease. The recommended pattern is to keep credentials out of build.gradle by loading them from the gitignored local.properties.

Step 1 — Add credentials to local.properties (do not commit):

bugsplat.database=your_database
bugsplat.clientId=your_client_id
bugsplat.clientSecret=your_client_secret

Step 2 — Load them in build.gradle and register per-ABI upload tasks:

// Load BugSplat credentials from local.properties
def localProps = new Properties()
def localPropsFile = rootProject.file('local.properties')
if (localPropsFile.exists()) {
    localPropsFile.withInputStream { localProps.load(it) }
}

ext {
    bugsplatDatabase = localProps.getProperty('bugsplat.database')
    bugsplatClientId = localProps.getProperty('bugsplat.clientId', '')
    bugsplatClientSecret = localProps.getProperty('bugsplat.clientSecret', '')
    // Use applicationId and versionName as the single source of truth
    bugsplatAppName = android.defaultConfig.applicationId
    bugsplatAppVersion = android.defaultConfig.versionName
}

// See example/build.gradle for the full implementation including:
//   - resolveSymbolUploadExecutable()   - downloads the symbol-upload binary
//   - uploadSymbolsForAbi(buildType, abi) - runs symbol-upload against
//     build/intermediates/merged_native_libs/<buildType>/merge<BuildType>NativeLibs/out/lib/<abi>/
//   - Per-ABI tasks (uploadBugSplatSymbolsDebugArm64-v8a, etc.)
//   - AllAbis task that chains the per-ABI tasks serially via mustRunAfter
//     (parallel uploads aren't safe — the symbol-upload binary uses a shared temp dir)

// Run symbol upload after assembleDebug
tasks.whenTaskAdded { task ->
    if (task.name == 'assembleDebug') {
        task.finalizedBy(tasks.named('uploadBugSplatSymbolsDebugAllAbis'))
    }
}

See example/build.gradle for the complete, working implementation. Key details:

• Intermediate path — AGP 8.6+ places merged native libs at merged_native_libs/<buildType>/merge<BuildType>NativeLibs/out/lib/<abi>/. Older AGPs used a flat merged_native_libs/<buildType>/out/lib/<abi>/ layout.
• Serial execution — the symbol-upload binary uses a shared temp directory, so per-ABI uploads must be chained via mustRunAfter rather than running in parallel.
• Missing ABIs — when Android Studio runs on a single-ABI device (e.g. an arm64 emulator), only that ABI's libs get built. Per-ABI tasks for other ABIs will log a warning and skip cleanly.

3. Using the Command-Line Tool

You can also use BugSplat's cross-platform tool, symbol-upload directly from the command line:

# Download the symbol-upload tool
# macOS
curl -sL -O "https://octomore.bugsplat.com/download/symbol-upload-macos" && chmod +x symbol-upload-macos

# Windows
Invoke-WebRequest -Uri "https://app.bugsplat.com/download/symbol-upload-windows.exe" -OutFile "symbol-upload-windows.exe"

# Linux
curl -sL -O  "https://app.bugsplat.com/download/symbol-upload-linux" && chmod +x symbol-upload-linux

# Upload symbols
./symbol-upload-macos -b DATABASE -a APPLICATION -v VERSION -i CLIENT_ID -s CLIENT_SECRET -d NATIVE_LIBS_DIR -f "**/*.so" -m

The -d argument specifies the directory containing the native libraries, and the -f argument specifies a glob pattern to find all the symbol files. The -m flag enables multi-threading for faster uploads.

Please refer to our documentation to learn more about how to use symbol-upload.

Native Library Deployment

When integrating BugSplat into your Android application, it's crucial to ensure that the native libraries (.so files) are properly deployed to the device. Here are the necessary configurations to include in your app's build.gradle file:

1. Match ABI Filters

   Ensure your app uses the same ABI filters as the BugSplat library:

   android {
       defaultConfig {
           ndk {
               abiFilters 'arm64-v8a', 'x86_64', 'armeabi-v7a'
           }
       }
   }

2. Prevent Symbol Stripping

   Configure packaging options to prevent stripping debug symbols from native libraries:

   android {
       packagingOptions {
           jniLibs {
               keepDebugSymbols += ['**/*.so']
               // Use uncompressed shared libraries with 16KB zip alignment (AGP 8.5.1+)
               // Required for Android 15+ devices with 16KB page sizes
               useLegacyPackaging false
           }
           doNotStrip '**/*.so'
       }
   }

   Note: Starting November 1st, 2025, all new apps and updates submitted to Google Play targeting Android 15+ must support 16 KB page sizes. The BugSplat SDK is built with 16KB ELF alignment. Using useLegacyPackaging false with AGP 8.5.1+ ensures proper 16KB zip alignment for uncompressed shared libraries.

3. Enable Native Library Extraction

   Add the following to your AndroidManifest.xml to ensure native libraries are extracted:

   <application
       android:extractNativeLibs="true"
       ... >

4. Enable JNI Debugging (for development)

   For development and testing, enable JNI debugging in your debug build type:

   android {
       buildTypes {
           debug {
               jniDebuggable true
           }
       }
   }

5. Add Storage Permissions (if needed)

   If your app needs to save crash dumps to external storage:

   <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" android:maxSdkVersion="32" />
   <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" android:maxSdkVersion="32" />

These configurations ensure that the BugSplat native libraries are properly included in your app and can function correctly to capture and report native crashes.

ANR Detection 🐌

The BugSplat Android SDK automatically detects and reports Application Not Responding (ANR) events on Android 11+ (API level 30+) using the ApplicationExitInfo API.

How It Works

When the system kills your app due to an ANR, the event is recorded by Android. On the next app launch, the SDK queries ActivityManager.getHistoricalProcessExitReasons() for new ANRs, reads the system-provided thread dump, and uploads it to BugSplat. ANR reports appear alongside crashes with the "Android.ANR" type.

The thread dump includes:

• Full Java stack traces for all threads in the process
• Native stack frames with BuildIds (symbolicated against uploaded .sym files)
• Lock contention information (which threads are holding/waiting for locks)

Configuration

ANR detection is enabled automatically when you call BugSplat.init() — no additional configuration needed. The SDK persists the timestamp of the last reported ANR in SharedPreferences to avoid duplicate uploads across launches.

Testing ANR Detection

To test ANR detection, use BugSplat.hang() to block the main thread in a native infinite loop:

// Call this on the main thread to trigger an ANR
BugSplat.hang();

After calling BugSplat.hang(), tap the screen to generate a pending input event — the system will show an ANR dialog after ~5 seconds. Choose "Close app" to kill the process. On the next app launch, the SDK will upload the ANR report to BugSplat.

The resulting thread dump includes a native frame for jniHang, which demonstrates end-to-end symbolication when your .sym files have been uploaded.

Supported Versions

ANR detection requires Android 11+ (API 30+). On older Android versions, the ApplicationExitInfo API is unavailable and ANR detection is silently disabled.

User Feedback 💬

BugSplat supports collecting non-crashing user feedback such as bug reports and feature requests. Feedback reports appear in BugSplat alongside crash reports with the "User Feedback" type.

Posting Feedback

Use BugSplat.postFeedback to submit feedback asynchronously, or BugSplat.postFeedbackBlocking for synchronous submission. The database, application, and version values are typically loaded from BuildConfig (see Loading config from local.properties):

// Async (returns immediately, runs on background thread)
BugSplat.postFeedback(
    BuildConfig.BUGSPLAT_DATABASE,
    BuildConfig.BUGSPLAT_APP_NAME,
    BuildConfig.BUGSPLAT_APP_VERSION,
    "Login button broken",     // title (required)
    "Nothing happens on tap",  // description
    "Jane",                    // user
    "jane@example.com",        // email
    null                       // appKey
);

// Blocking (returns true on success)
boolean success = BugSplat.postFeedbackBlocking(
    BuildConfig.BUGSPLAT_DATABASE,
    BuildConfig.BUGSPLAT_APP_NAME,
    BuildConfig.BUGSPLAT_APP_VERSION,
    "Login button broken", "Nothing happens on tap",
    "Jane", "jane@example.com", null
);

File Attachments

Pass a list of File objects to attach files to the feedback report:

List<File> attachments = new ArrayList<>();
attachments.add(new File(getFilesDir(), "screenshot.png"));
attachments.add(new File(getFilesDir(), "app.log"));

BugSplat.postFeedback(
    BuildConfig.BUGSPLAT_DATABASE,
    BuildConfig.BUGSPLAT_APP_NAME,
    BuildConfig.BUGSPLAT_APP_VERSION,
    "Login button broken", "Nothing happens on tap",
    "Jane", "jane@example.com", null,
    attachments
);

Custom Attributes

Attach arbitrary key/value metadata to feedback reports:

Map<String, String> attributes = new HashMap<>();
attributes.put("environment", "production");
attributes.put("user_tier", "premium");

BugSplat.postFeedback(
    BuildConfig.BUGSPLAT_DATABASE,
    BuildConfig.BUGSPLAT_APP_NAME,
    BuildConfig.BUGSPLAT_APP_VERSION,
    "Login button broken", "Nothing happens on tap",
    "Jane", "jane@example.com", null,
    null,        // attachments
    attributes
);

Example Feedback Dialog

The example app includes a simple feedback dialog using Android's AlertDialog. See MainActivity.java for the implementation. The dialog collects a subject and optional description, then posts feedback using BugSplat.postFeedbackBlocking on a background thread.

Sample Applications 🧑‍🏫

Example App

The repository includes an example app that demonstrates how to use the BugSplat Android SDK. The example app is located in the example directory.

To run the example app:

1. Open the project in Android Studio
2. Select "Example App" from the run configuration dropdown in the toolbar
3. Click the run button to build and run the app on your device or emulator

The example app demonstrates:

• Automatically initializing the BugSplat SDK at app startup
• Triggering a crash for testing purposes
• Triggering an ANR (via BugSplat.hang()) to test ANR detection and native frame symbolication
• Submitting user feedback via a dialog
• Setting custom attributes via a dialog
• Handling errors during initialization

For more information, see the Example App README.

Building Native Dependencies 🔨

The BugSplat Android SDK includes prebuilt native libraries, but you can also build them from source with 16KB page size support.

Prerequisites

• Android NDK 28.2.13676358 or higher (recommended for 16KB page size support)
• depot_tools (for building Crashpad) - Installation guide
• CMake and Ninja

NDK 28+ Setup (Required for Crashpad)

NDK 28 removed the legacy standalone toolchain binaries that Crashpad's build system expects (e.g., aarch64-linux-android-ar). You need to create symlinks to the LLVM equivalents:

cd $ANDROID_NDK/toolchains/llvm/prebuilt/darwin-x86_64/bin  # or linux-x86_64 on Linux

# Create symlinks for aarch64 (arm64-v8a)
ln -sf llvm-ar aarch64-linux-android-ar
ln -sf llvm-nm aarch64-linux-android-nm
ln -sf llvm-strip aarch64-linux-android-strip
ln -sf llvm-objcopy aarch64-linux-android-objcopy
ln -sf llvm-ranlib aarch64-linux-android-ranlib
ln -sf llvm-readelf aarch64-linux-android-readelf

# Create symlinks for arm (armeabi-v7a)
ln -sf llvm-ar arm-linux-androideabi-ar
ln -sf llvm-nm arm-linux-androideabi-nm
ln -sf llvm-strip arm-linux-androideabi-strip
ln -sf llvm-objcopy arm-linux-androideabi-objcopy
ln -sf llvm-ranlib arm-linux-androideabi-ranlib
ln -sf llvm-readelf arm-linux-androideabi-readelf

# Create symlinks for x86_64
ln -sf llvm-ar x86_64-linux-android-ar
ln -sf llvm-nm x86_64-linux-android-nm
ln -sf llvm-strip x86_64-linux-android-strip
ln -sf llvm-objcopy x86_64-linux-android-objcopy
ln -sf llvm-ranlib x86_64-linux-android-ranlib
ln -sf llvm-readelf x86_64-linux-android-readelf

Building from Source

1. Clone with submodules:

   git clone --recurse-submodules https://github.com/BugSplat-Git/bugsplat-android
   cd bugsplat-android

2. Set environment variables (optional):

   # If your NDK is in a non-standard location
   export ANDROID_NDK="/path/to/your/ndk"
   
   # If depot_tools is in a non-standard location
   export DEPOT_TOOLS="/path/to/depot_tools"

3. Run the build script:

   ./scripts/build-all.sh

   Or build components individually:

   ./scripts/build-libcurl.sh   # Build libcurl with BoringSSL
   ./scripts/build-crashpad.sh  # Build Crashpad

What Gets Built

The build scripts compile the following with 16KB page size alignment:

• libcurl - HTTP client library (with BoringSSL for TLS)
• Crashpad - Crash reporting framework
  • libcrashpad_handler.so - Crash handler process
  • libclient.a - Client library for crash capture
  • libcommon.a - Common utilities
  • libutil.a - Utility functions
  • libbase.a - Base library (from mini_chromium)

All libraries are built for:

• arm64-v8a
• armeabi-v7a
• x86_64

16KB Page Size Configuration

The build uses these flags for 16KB page size compatibility:

# In crashpad args.gn
extra_ldflags = "-static-libstdc++ -Wl,-z,max-page-size=16384"

# In libcurl CMake
-DCMAKE_SHARED_LINKER_FLAGS="-Wl,-z,max-page-size=16384"

Building the Release AAR 📦

To build the BugSplat Android SDK as a release AAR file:

1. Navigate to the project directory:

   cd bugsplat-android

2. Build the release AAR:

   ./gradlew app:assembleRelease

   Or to build only the AAR bundle:

   ./gradlew app:bundleReleaseAar

3. Find the output:

   The AAR file will be located at:

   app/build/outputs/aar/bugsplat-android-release.aar
   

Build Variants

You can also build the debug variant:

./gradlew app:assembleDebug
# Output: app/build/outputs/aar/bugsplat-android-debug.aar

Or build all variants at once:

./gradlew app:assemble

Contributing 🤝

BugSplat is an open-source project, and we welcome contributions from the community. Please create an issue or open a pull request if you have a suggestion or need additional help.