BugScreen
docsandroid

Android SDK

v0.5.0

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

Installation

BugScreen is published to Maven Central. Make sure mavenCentral() is in your repositories list (typically in settings.gradle.kts):

settings.gradle.kts
kotlin
dependencyResolutionManagement {
    repositories {
        mavenCentral()
    }
}

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

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

Setup

Initialize BugScreen in your Application class:

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

        BugScreenSDK.start(
            BugScreenConfig.Builder(this)
                .apiKey("fb_your_api_key_here")
                .enableScreenshotDetection(true)
                .enableSdkLogging(BuildConfig.DEBUG)
                .build()
        )
    }
}

Request permissions

For screenshot detection to work on Android 13 and below, you need to request the appropriate permission. Android 14+ doesn't require any permission to detect screenshots — but if you want the SDK to auto-attach the screenshot to the report, it will prompt the user for photo access the first time. If they decline, the user simply picks the screenshot from the photo picker instead. The SDK provides helper functions to simplify the detection-side permission.

Simple approach (recommended)

Use the SDK's built-in permission request function:

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)
Advanced approach

For custom permission UI, get the required permission string:

kotlin
// Get version-specific permission (null on Android 14+)
val permission = BugScreenSDK.getRequiredPermission()
if (permission != null) {
    // Use Android's permission request APIs
    requestPermissions(arrayOf(permission), REQUEST_CODE)
}
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.

Usage

Automatic screenshot detection

When users take a screenshot, BugScreen automatically shows a bug report dialog. That's it.

Manual triggering

Open the bug report screen programmatically:

kotlin
// Without screenshot
BugScreenSDK.openBugReportScreen(context)

// With screenshot
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.

Configuration

OptionDefaultDescription
apiKey(String)RequiredYour API key from the BugScreen console
enableScreenshotDetection(Boolean)trueAuto-detect screenshots and show report UI
enableSdkLogging(Boolean)falseEnable debug logs (use BuildConfig.DEBUG)

What gets collected?

BugScreen automatically collects this information with each report:

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

Ready to get started?

Create an account to get your API key.

Get started