
In-app bug reporting with screenshot capture, image markup and crop editor, Markdown description toolbar, image picker, redacting diagnostic logs, and pluggable transport for multipart sending.
Drop-in in-app bug reporting for Compose Multiplatform — Android, iOS, desktop (JVM) and web (Wasm and JS).
<input type=file>).BugReport; send it anywhere. A Ktor multipart sender is
included.Recorded from the sample app: a booking fails, and the form opens with that screen attached. The top row is an Android 16 emulator, where the user took a screenshot; the bottom row is an iOS 27 simulator, where they tapped the bug icon and added a photo with the photo picker.
| Describe it in Markdown | Circle the problem | Crop to what matters | What your sender gets |
|---|---|---|---|
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
The same UI on desktop, following the app's light or dark theme:
// build.gradle.kts of your shared module
kotlin {
sourceSets {
commonMain.dependencies {
implementation("io.github.antonudovychenko:bugreport:0.1.0")
// Optional: ready-made multipart sender for a Ktor HttpClient.
implementation("io.github.antonudovychenko:bugreport-ktor:0.1.0")
}
}
}Requires Kotlin 2.3+, Compose Multiplatform 1.11+, Android minSdk 24.
Wrap your app's content in BugReportHost, inside your MaterialTheme:
val bugReports = rememberBugReportController()
MaterialTheme {
BugReportHost(
sender = KtorBugReportSender(httpClient, "https://api.example.com/bug-reports"),
controller = bugReports,
logs = { logBuffer.export() },
metadata = { mapOf("buildVersion" to BuildConfig.VERSION_NAME) },
) {
AppContent(onReportBug = bugReports::open)
}
}BugReportController is a plain object, so it can also live in your DI container and be opened
from anywhere — a menu item, a shake detector, a debug drawer.
val sender = BugReportSender { report ->
// report.description — Markdown
// report.plainTextDescription — the same, formatting removed
// report.images — JPEGs with markup and crop baked in
// report.logs — the log snapshot, or null
// report.device — e.g. "Android 15 (API 35) (Google Pixel 9)"
// report.metadata — whatever you passed to BugReportHost
myApi.fileIssue(report)
}Throw to report a failure: the draft stays open so nothing the user typed is lost. Throw
BugReportSendException("You've sent a lot of reports — try again in an hour") to show your own
message instead of the generic one.
The Ktor sender posts multipart/form-data with a description field, a device field, one field
per metadata entry, one screenshot file part per image and a logs file part. Rename or drop any
part with MultipartBugReportFormat, or call HttpClient.submitBugReport(url, report, format)
from your own sender when the URL or client is only known at send time.
val logBuffer = DiagnosticLogBuffer() // 1 MiB, oldest lines dropped first
// From your logger:
logBuffer.append(level = "WARN", tag = "Sync", message = "push failed", throwable = e)Bearer tokens, JWTs, e-mail addresses, credential-looking query parameters and
password=/token=/secret=/api_key= pairs are redacted before a line is stored. Add your own
rules with DiagnosticLogBuffer(redact = { redactDiagnosticText(it).replace(myPattern, "[X]") }).
BugReportConfig(
maxImages = 4,
openOnSystemScreenshot = true, // iOS, Android 14+
captureScreenshotOnOpen = true,
allowImagePicking = true,
maxImageDimension = 1600, // keeps JPEG encoding fast, uploads small
jpegQuality = 80,
penColor = Color(0xFFE53935),
penWidth = 4.dp,
showSuccessDialog = true,
attachLogsByDefault = true,
)ImageMarkupEditor(image, onDone, onCancel) is public and depends on nothing else here — use it
anywhere you want a user to annotate or crop an ImageBitmap.
sample/ is a small travel app whose Book button always fails — report it, then open
Inbox to see exactly what a BugReportSender receives: the Markdown, the edited images, the
redacted logs and the device.
./gradlew :sample:run # desktop
./gradlew :sample:wasmJsBrowserDevelopmentRun # web, opens a browser
./gradlew :sample-android:installDebug # Android device or emulator
open sample-ios/iosApp.xcodeproj # iOS: pick a simulator in Xcode and RunThe Xcode project builds the shared UI through Gradle (:sample:embedAndSignAppleFrameworkForXcode
in a Run Script phase), so the first build takes a few minutes. To build it from the command line:
xcodebuild -project sample-ios/iosApp.xcodeproj -scheme iosApp -destination 'platform=iOS Simulator,name=iPhone 17' buildTo run on a device, set TEAM_ID in sample-ios/Configuration/Config.xcconfig.
On Android 14+ take a screenshot (power + volume down, or adb shell input keyevent 120 on an
emulator) to open the form without touching the app's own button.
| Opens on system screenshot | Image picker | |
|---|---|---|
| Android | API 34+ (Activity.ScreenCaptureCallback; the library declares DETECT_SCREEN_CAPTURE) |
Photo Picker |
| iOS | Yes (UIApplicationUserDidTakeScreenshotNotification) |
PHPicker; HEIC is converted to JPEG |
| Desktop | No — open it from a menu | AWT file dialog |
| Web | No — open it from a menu | <input type=file> |
The capture is of the content inside BugReportHost — not other windows, dialogs or system UI.
On web and desktop the content is routed through a graphics layer only for the two frames a capture
takes, because a permanent one breaks input there
(compose-multiplatform#3230).
To use an unreleased checkout from your app, add includeBuild("path/to/kmp-bugreport") to its
settings.gradle.kts and depend on the coordinates without a version.
./gradlew jvmTest # the shared tests, on the JVM
./gradlew compileKotlinIosSimulatorArm64 compileKotlinWasmJs compileKotlinJs compileAndroidMainThe shared tests compile for every target; the browser test runners are disabled so no headless browser is needed.
Publishing uses com.vanniktech.maven.publish from .github/workflows/publish.yml:
VERSION_NAME in gradle.properties to the release version (no -SNAPSHOT).v0.1.0. The workflow tests, builds every target on macOS, signs and
uploads to the Central Portal.The workflow needs the repository secrets MAVEN_CENTRAL_USERNAME, MAVEN_CENTRAL_PASSWORD (a
Central Portal user token), SIGNING_KEY (an ASCII-armoured GPG private key) and
SIGNING_KEY_PASSWORD.
Issues and pull requests are welcome. main is protected: changes land through a pull request that
passes CI and is approved by the maintainer (CODEOWNERS). CI on pull requests
from forks starts once a maintainer approves the run.
Apache License 2.0 — see LICENSE.
Drop-in in-app bug reporting for Compose Multiplatform — Android, iOS, desktop (JVM) and web (Wasm and JS).
<input type=file>).BugReport; send it anywhere. A Ktor multipart sender is
included.Recorded from the sample app: a booking fails, and the form opens with that screen attached. The top row is an Android 16 emulator, where the user took a screenshot; the bottom row is an iOS 27 simulator, where they tapped the bug icon and added a photo with the photo picker.
| Describe it in Markdown | Circle the problem | Crop to what matters | What your sender gets |
|---|---|---|---|
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
The same UI on desktop, following the app's light or dark theme:
// build.gradle.kts of your shared module
kotlin {
sourceSets {
commonMain.dependencies {
implementation("io.github.antonudovychenko:bugreport:0.1.0")
// Optional: ready-made multipart sender for a Ktor HttpClient.
implementation("io.github.antonudovychenko:bugreport-ktor:0.1.0")
}
}
}Requires Kotlin 2.3+, Compose Multiplatform 1.11+, Android minSdk 24.
Wrap your app's content in BugReportHost, inside your MaterialTheme:
val bugReports = rememberBugReportController()
MaterialTheme {
BugReportHost(
sender = KtorBugReportSender(httpClient, "https://api.example.com/bug-reports"),
controller = bugReports,
logs = { logBuffer.export() },
metadata = { mapOf("buildVersion" to BuildConfig.VERSION_NAME) },
) {
AppContent(onReportBug = bugReports::open)
}
}BugReportController is a plain object, so it can also live in your DI container and be opened
from anywhere — a menu item, a shake detector, a debug drawer.
val sender = BugReportSender { report ->
// report.description — Markdown
// report.plainTextDescription — the same, formatting removed
// report.images — JPEGs with markup and crop baked in
// report.logs — the log snapshot, or null
// report.device — e.g. "Android 15 (API 35) (Google Pixel 9)"
// report.metadata — whatever you passed to BugReportHost
myApi.fileIssue(report)
}Throw to report a failure: the draft stays open so nothing the user typed is lost. Throw
BugReportSendException("You've sent a lot of reports — try again in an hour") to show your own
message instead of the generic one.
The Ktor sender posts multipart/form-data with a description field, a device field, one field
per metadata entry, one screenshot file part per image and a logs file part. Rename or drop any
part with MultipartBugReportFormat, or call HttpClient.submitBugReport(url, report, format)
from your own sender when the URL or client is only known at send time.
val logBuffer = DiagnosticLogBuffer() // 1 MiB, oldest lines dropped first
// From your logger:
logBuffer.append(level = "WARN", tag = "Sync", message = "push failed", throwable = e)Bearer tokens, JWTs, e-mail addresses, credential-looking query parameters and
password=/token=/secret=/api_key= pairs are redacted before a line is stored. Add your own
rules with DiagnosticLogBuffer(redact = { redactDiagnosticText(it).replace(myPattern, "[X]") }).
BugReportConfig(
maxImages = 4,
openOnSystemScreenshot = true, // iOS, Android 14+
captureScreenshotOnOpen = true,
allowImagePicking = true,
maxImageDimension = 1600, // keeps JPEG encoding fast, uploads small
jpegQuality = 80,
penColor = Color(0xFFE53935),
penWidth = 4.dp,
showSuccessDialog = true,
attachLogsByDefault = true,
)ImageMarkupEditor(image, onDone, onCancel) is public and depends on nothing else here — use it
anywhere you want a user to annotate or crop an ImageBitmap.
sample/ is a small travel app whose Book button always fails — report it, then open
Inbox to see exactly what a BugReportSender receives: the Markdown, the edited images, the
redacted logs and the device.
./gradlew :sample:run # desktop
./gradlew :sample:wasmJsBrowserDevelopmentRun # web, opens a browser
./gradlew :sample-android:installDebug # Android device or emulator
open sample-ios/iosApp.xcodeproj # iOS: pick a simulator in Xcode and RunThe Xcode project builds the shared UI through Gradle (:sample:embedAndSignAppleFrameworkForXcode
in a Run Script phase), so the first build takes a few minutes. To build it from the command line:
xcodebuild -project sample-ios/iosApp.xcodeproj -scheme iosApp -destination 'platform=iOS Simulator,name=iPhone 17' buildTo run on a device, set TEAM_ID in sample-ios/Configuration/Config.xcconfig.
On Android 14+ take a screenshot (power + volume down, or adb shell input keyevent 120 on an
emulator) to open the form without touching the app's own button.
| Opens on system screenshot | Image picker | |
|---|---|---|
| Android | API 34+ (Activity.ScreenCaptureCallback; the library declares DETECT_SCREEN_CAPTURE) |
Photo Picker |
| iOS | Yes (UIApplicationUserDidTakeScreenshotNotification) |
PHPicker; HEIC is converted to JPEG |
| Desktop | No — open it from a menu | AWT file dialog |
| Web | No — open it from a menu | <input type=file> |
The capture is of the content inside BugReportHost — not other windows, dialogs or system UI.
On web and desktop the content is routed through a graphics layer only for the two frames a capture
takes, because a permanent one breaks input there
(compose-multiplatform#3230).
To use an unreleased checkout from your app, add includeBuild("path/to/kmp-bugreport") to its
settings.gradle.kts and depend on the coordinates without a version.
./gradlew jvmTest # the shared tests, on the JVM
./gradlew compileKotlinIosSimulatorArm64 compileKotlinWasmJs compileKotlinJs compileAndroidMainThe shared tests compile for every target; the browser test runners are disabled so no headless browser is needed.
Publishing uses com.vanniktech.maven.publish from .github/workflows/publish.yml:
VERSION_NAME in gradle.properties to the release version (no -SNAPSHOT).v0.1.0. The workflow tests, builds every target on macOS, signs and
uploads to the Central Portal.The workflow needs the repository secrets MAVEN_CENTRAL_USERNAME, MAVEN_CENTRAL_PASSWORD (a
Central Portal user token), SIGNING_KEY (an ASCII-armoured GPG private key) and
SIGNING_KEY_PASSWORD.
Issues and pull requests are welcome. main is protected: changes land through a pull request that
passes CI and is approved by the maintainer (CODEOWNERS). CI on pull requests
from forks starts once a maintainer approves the run.
Apache License 2.0 — see LICENSE.