bugscreen
docsandroid

Android SDK

v1.3.0

Integrate BugScreen into your Android app in minutes. Kotlin, Jetpack Compose, Gradle.

Installation

Add the dependency to your module's build.gradle.kts:

build.gradle.kts
kotlin
dependencies {
    implementation("app.bugscreen:android:1.3.0")
}

Requires Android 7.0+ (API 24) and Kotlin 2.0+.

Setup

BugScreen is for dev/QA — gate BugScreenSDK.start(...) in your Application class so it doesn't run for end users. Pick one:

Tester-flag guard

Runs on production builds for users you flag as testers — useful for dogfooding.

MyApp.kt
kotlin
class MyApp : Application() {
    override fun onCreate() {
        super.onCreate()

        // User.isTester() is pseudocode — replace with your tester signal.
        if (User.isTester()) {
            BugScreenSDK.start(
                BugScreenConfig.Builder(this)
                    .apiKey("fb_your_api_key_here")
                    .screenshotDetection(true)
                    .requestPermissionsOnStart(true)
                    .build()
            )
        }
    }
}

debugImplementation + no-op

Only the no-op stub ships in your release APK. Pair the real SDK on debug with app.bugscreen:android-no-op on release; both expose the same API so your Application class compiles unchanged.

build.gradle.kts
kotlin
dependencies {
    debugImplementation("app.bugscreen:android:1.3.0")
    releaseImplementation("app.bugscreen:android-no-op:1.3.0")
}

Then call BugScreenSDK.start(...) from your Application class with no guard — release builds resolve the no-op and do nothing.

MyApp.kt
kotlin
class MyApp : Application() {
    override fun onCreate() {
        super.onCreate()

        BugScreenSDK.start(
            BugScreenConfig.Builder(this)
                .apiKey("fb_your_api_key_here")
                .screenshotDetection(true)
                .requestPermissionsOnStart(true)
                .build()
        )
    }
}

Request permissions

Android 14+: no permission needed to detect screenshots. The SDK prompts once for photo access to auto-attach the screenshot; if denied, the user picks it from the photo picker instead.

Android 13 and below: needs a runtime permission to detect screenshots. Opt in with .requestPermissionsOnStart(true) to have the SDK prompt automatically, or use the fine-grained helpers below.

kotlin
// Check if permission is needed
if (BugScreenSDK.shouldRequestPermission(this)) {
    // Request permission with callback
    BugScreenSDK.requestScreenshotPermission(this) { granted ->
        if (granted) {
            // Permission granted - screenshot detection enabled
        } else {
            // Permission denied - manual triggering still works
        }
    }
}

// Or just check permission status
val hasPermission = BugScreenSDK.hasScreenshotPermission(this)
Note: On Android 14+ no permission is needed for screenshot detection itself. The SDK may prompt the user once for photo access so it can auto-attach the screenshot to the report; if they decline, the report screen falls back to the system photo picker.

Permissions added to your app

BugScreen's manifest is merged into your app's manifest, so these <uses-permission> entries appear in your Play Console listing if you ship the SDK in your production app:

  • INTERNET — upload bug reports.
  • READ_EXTERNAL_STORAGE (Android 12 and below only) — read the latest screenshot from MediaStore.
  • READ_MEDIA_IMAGES (Android 13+) — same lookup on modern Android; requested opt-in at runtime.
  • DETECT_SCREEN_CAPTURE (Android 14+) — install-time, silent; lets the SDK know when a screenshot is taken.

Usage

Automatic screenshot detection

When users take a screenshot, BugScreen automatically shows a bug report dialog. That's it. Reporters can attach up to four screenshots to a single report from the in-app dialog.

Manual triggering

Open the bug report screen programmatically:

kotlin
// Without screenshot
BugScreenSDK.openBugReportScreen(context)

// With screenshot (screenshotUri: android.net.Uri)
BugScreenSDK.openBugReportScreen(context, screenshotUri)

Logging

Add context to bug reports with application logs:

kotlin
BugScreenSDK.log(LogLevel.INFO, "User tapped checkout button")
BugScreenSDK.log(LogLevel.ERROR, "Payment failed: ${error.message}")

Logs are automatically included with every bug report.

Custom data

Attach arbitrary key/value pairs to every subsequent bug report:

kotlin
// Replace the whole map:
BugScreenSDK.setCustomData(mapOf(
    "env" to "staging",
    "buildType" to "debug",
    "userTier" to "pro",
))

// Set or remove a single key:
BugScreenSDK.setCustomData("userId", "abc-123")
BugScreenSDK.removeCustomData("userId")

// Merge a map without replacing existing keys:
BugScreenSDK.addCustomData(mapOf("plan" to "pro", "region" to "eu"))

// Remove all custom data:
BugScreenSDK.clearCustomData()

Call any time after start(). The values are read when the bug report screen opens and appear in the report's metadata.

Configuration

OptionDefaultDescription
apiKey(String)RequiredYour API key from the BugScreen console
screenshotDetection(Boolean)trueAuto-detect screenshots and show report UI
debug(Boolean)falseEnable SDK debug behavior (use BuildConfig.DEBUG)
requestPermissionsOnStart(Boolean)falseAuto-request the runtime permission needed for screenshot detection on Android 13 and below, on the first resumed Activity. No-op on Android 14+ or if already granted.

What gets collected?

BugScreen automatically collects this information with each report:

  • •Device model & manufacturer
  • •Android version & API level
  • •App version & package name
  • •Screen size (dp and pixels) & density
  • •Memory (total & available)
  • •Device locale
  • •BugScreen SDK version

Start shipping bug reports

Create an account to start shipping bug reports from your app.

Get started