bugscreen
HomeDocsAndroid

Android SDK

v1.5.0

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

Sample app

BugScreen Travel is a small Jetpack Compose app that wires up every integration point, with the debugImplementation + no-op release split.

View on GitHub

Installation

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

build.gradle.kts
kotlin
dependencies {
    implementation("app.bugscreen:android:1.5.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
import app.bugscreen.android.BugScreenConfig
import app.bugscreen.android.BugScreenSDK

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.5.0")
    releaseImplementation("app.bugscreen:android-no-op:1.5.0")
}

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

MyApp.kt
kotlin
import app.bugscreen.android.BugScreenConfig
import app.bugscreen.android.BugScreenSDK

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
import app.bugscreen.android.BugScreenSDK
import app.bugscreen.android.LogLevel

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.

User accounts

Identify the account a report is filed under so a triager can reproduce the bug. It renders as a dedicated Account section at the top of the created issue, and the role becomes a filterable label.

kotlin
import app.bugscreen.android.BugScreenSDK
import app.bugscreen.android.BugScreenUser

// Set the current account (id required; role and email optional):
BugScreenSDK.setUser(id = "pro-user-8823", role = "admin")

// Or read it fresh at capture time — ideal when QA switches logins mid-session:
BugScreenSDK.setUserProvider {
    session.currentUser?.let { BugScreenUser(id = it.id, role = it.role) }
}

// Clear it on logout:
BugScreenSDK.clearUser()

Only role becomes a label (non-PII); id and email stay in the issue body. Pass email only when you want a contactable address in the tracker — nothing is auto-collected.

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
  • •Appearance (dark / light)
  • •BugScreen SDK version

Start shipping bug reports

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