Skip to content

The only tool you need to know what is happening and how to fix it.

Android added to docs/fe/be

ddux37e1b519ce13
diff --git a/backend/app/controllers/auth.controller.go b/backend/app/controllers/auth.controller.go
index d60b43e7..54325c4d 100644
--- a/backend/app/controllers/auth.controller.go
+++ b/backend/app/controllers/auth.controller.go
@@ -154,7 +154,7 @@ func (a authController) Register(c *gin.Context) {
if !validFrameworks[request.Framework] {
traceway.CaptureMessage("Invalid framework received during registration: " + request.Framework)
- c.JSON(http.StatusBadRequest, gin.H{"error": "Framework must be one of: gin, fiber, chi, fasthttp, stdlib, custom, react, svelte, vuejs, jquery, hono, cloudflare, opentelemetry, symfony, flutter"})
+ c.JSON(http.StatusBadRequest, gin.H{"error": "Framework must be one of: gin, fiber, chi, fasthttp, stdlib, custom, react, svelte, vuejs, jquery, hono, cloudflare, opentelemetry, symfony, flutter, android"})
return
}
diff --git a/backend/app/controllers/oauth.controller.go b/backend/app/controllers/oauth.controller.go
index 77a05b1b..58d472f1 100644
--- a/backend/app/controllers/oauth.controller.go
+++ b/backend/app/controllers/oauth.controller.go
@@ -163,7 +163,7 @@ func (a oauthController) FinishSetup(c *gin.Context) {
}
if !validFrameworks[request.Framework] {
- c.JSON(http.StatusBadRequest, gin.H{"error": "Framework must be one of: gin, fiber, chi, fasthttp, stdlib, custom, react, svelte, vuejs, jquery, hono, cloudflare, opentelemetry, symfony, flutter"})
+ c.JSON(http.StatusBadRequest, gin.H{"error": "Framework must be one of: gin, fiber, chi, fasthttp, stdlib, custom, react, svelte, vuejs, jquery, hono, cloudflare, opentelemetry, symfony, flutter, android"})
return
}
diff --git a/backend/app/controllers/project.controller.go b/backend/app/controllers/project.controller.go
index 7f4f132d..b2a357af 100644
--- a/backend/app/controllers/project.controller.go
+++ b/backend/app/controllers/project.controller.go
@@ -41,6 +41,7 @@ var validFrameworks = map[string]bool{
"symfony": true,
// Mobile frameworks
"flutter": true,
+ "android": true,
}
// Project name validation regex: allows alphanumeric, spaces, hyphens, and underscores
@@ -88,7 +89,7 @@ func (p projectController) CreateProject(c *gin.Context) {
if !validFrameworks[request.Framework] {
traceway.CaptureMessage("Invalid framework received: " + request.Framework)
- c.JSON(http.StatusBadRequest, gin.H{"error": "Framework must be one of: gin, fiber, chi, fasthttp, stdlib, custom, react, svelte, vuejs, jquery, hono, cloudflare, opentelemetry, symfony, flutter"})
+ c.JSON(http.StatusBadRequest, gin.H{"error": "Framework must be one of: gin, fiber, chi, fasthttp, stdlib, custom, react, svelte, vuejs, jquery, hono, cloudflare, opentelemetry, symfony, flutter, android"})
return
}
diff --git a/docs/components/FrameworkPicker.jsx b/docs/components/FrameworkPicker.jsx
index c483c685..1ba9c96a 100644
--- a/docs/components/FrameworkPicker.jsx
+++ b/docs/components/FrameworkPicker.jsx
@@ -168,6 +168,14 @@ const FRAMEWORKS = [
href: "/client/flutter",
badge: "new",
},
+ {
+ value: "android",
+ label: "Android",
+ description: "Native Android (Kotlin/Java) apps with automatic exception capture, logs, HTTP, and navigation breadcrumbs.",
+ icon: "/android.png",
+ href: "/client/android",
+ badge: "new",
+ },
];
export default function FrameworkPicker() {
diff --git a/docs/components/SdkContext.jsx b/docs/components/SdkContext.jsx
index d7ffa3c5..bcd02cf9 100644
--- a/docs/components/SdkContext.jsx
+++ b/docs/components/SdkContext.jsx
@@ -22,6 +22,7 @@ export const SDK_OPTIONS = [
{ value: 'js-nextjs', label: 'Next.js (OTel)' },
{ value: 'php-symfony', label: 'Symfony' },
{ value: 'flutter', label: 'Flutter' },
+ { value: 'android', label: 'Android' },
]
const STORAGE_KEY = 'traceway-docs-sdk'
@@ -46,6 +47,7 @@ const PATH_SDK_MAP = {
'nextjs': 'js-nextjs',
'symfony': 'php-symfony',
'flutter': 'flutter',
+ 'android': 'android',
}
const SdkContext = createContext({
diff --git a/docs/components/SdkSelector.jsx b/docs/components/SdkSelector.jsx
index a8c9afe8..c941afeb 100644
--- a/docs/components/SdkSelector.jsx
+++ b/docs/components/SdkSelector.jsx
@@ -23,6 +23,7 @@ const SDK_QUICK_START = {
'cloudflare': '/client/cloudflare',
'php-symfony': '/client/symfony',
'flutter': '/client/flutter',
+ 'android': '/client/android',
}
export default function SdkSelector() {
diff --git a/docs/pages/client/_meta.json b/docs/pages/client/_meta.json
index a984ecb9..2ff65b49 100644
--- a/docs/pages/client/_meta.json
+++ b/docs/pages/client/_meta.json
@@ -24,5 +24,6 @@
"otel": "OpenTelemetry",
"cloudflare": "Cloudflare Workers",
"symfony": "Symfony",
- "flutter": "Flutter"
+ "flutter": "Flutter",
+ "android": "Android"
}
diff --git a/docs/pages/client/android/_meta.json b/docs/pages/client/android/_meta.json
new file mode 100644
index 00000000..8393d864
--- /dev/null
+++ b/docs/pages/client/android/_meta.json
@@ -0,0 +1,3 @@
+{
+ "index": "Quick Start"
+}
diff --git a/docs/pages/client/android/index.mdx b/docs/pages/client/android/index.mdx
new file mode 100644
index 00000000..4ee05e2f
--- /dev/null
+++ b/docs/pages/client/android/index.mdx
@@ -0,0 +1,234 @@
+# Android Quick Start
+
+Integrate Traceway into your native Android application with the [`com.tracewayapp:traceway`](https://central.sonatype.com/artifact/com.tracewayapp/traceway) library from Maven Central.
+
+## Installation
+
+Add the dependency to your app module's `build.gradle.kts`:
+
+```kotlin
+dependencies {
+ implementation("com.tracewayapp:traceway:1.0.0")
+}
+```
+
+Maven Central is enabled by default in modern Android projects — no extra `repositories { ... }` entry is required.
+
+## Setup
+
+Initialize the SDK from your `Application.onCreate()`. This wraps the whole process — every uncaught exception, on every thread, is captured automatically:
+
+```kotlin
+import android.app.Application
+import com.tracewayapp.traceway.Traceway
+import com.tracewayapp.traceway.TracewayOptions
+
+class MyApp : Application() {
+ override fun onCreate() {
+ super.onCreate()
+ Traceway.init(
+ application = this,
+ connectionString = "your-token@https://traceway.example.com/api/report",
+ options = TracewayOptions(version = "1.0.0"),
+ )
+ }
+}
+```
+
+Register the application class in `AndroidManifest.xml` and add the `INTERNET` permission so reports can leave the device:
+
+```xml
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+ <uses-permission android:name="android.permission.INTERNET" />
+ <application android:name=".MyApp" ...>
+ ...
+ </application>
+</manifest>
+```
+
+## Capture Errors Manually
+
+```kotlin
+import com.tracewayapp.traceway.Traceway
+
+// Capture a caught exception
+try {
+ riskyOperation()
+} catch (e: Throwable) {
+ Traceway.captureException(e)
+}
+
+// Capture a message
+Traceway.captureMessage("User completed onboarding")
+
+// Force send pending events
+Traceway.flush()
+```
+
+## With Options
+
+`TracewayOptions` accepts the following parameters. Field names mirror the Flutter SDK so configuration can be ported directly.
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `sampleRate` | `Double` | `1.0` | Event sampling rate (0.0 to 1.0) |
+| `debug` | `Boolean` | `false` | Print debug info to logcat |
+| `version` | `String` | `""` | App version string |
+| `debounceMs` | `Long` | `1500` | Milliseconds before sending batched events |
+| `retryDelayMs` | `Long` | `10000` | Retry delay in ms on failed uploads |
+| `maxPendingExceptions` | `Int` | `5` | Max exceptions held in memory before oldest is dropped |
+| `persistToDisk` | `Boolean` | `true` | Persist pending exceptions to disk so they survive app restarts |
+| `maxLocalFiles` | `Int` | `5` | Max exception files stored on disk |
+| `localFileMaxAgeHours` | `Int` | `12` | Hours after which unsynced local files are deleted |
+| `captureLogs` | `Boolean` | `true` | Mirror every `println` / `System.out` / `System.err` line into the rolling log buffer |
+| `captureNetwork` | `Boolean` | `true` | Record network events sent through `TracewayOkHttpInterceptor` |
+| `captureNavigation` | `Boolean` | `true` | Record activity push / pop transitions |
+| `eventsWindowMs` | `Long` | `10000` | Rolling window kept in the log/action buffers (ms) |
+| `eventsMaxCount` | `Int` | `200` | Hard cap applied independently to logs and actions |
+| `screenCapture` | `Boolean` | `false` | **No effect on Android** — accepted for API parity |
+| `capturePixelRatio` | `Double` | `0.75` | **No effect on Android** |
+| `maxBufferFrames` | `Int` | `150` | **No effect on Android** |
+| `fps` | `Int` | `15` | **No effect on Android** |
+
+```kotlin
+Traceway.init(
+ application = this,
+ connectionString = "your-token@https://traceway.example.com/api/report",
+ options = TracewayOptions(
+ sampleRate = 0.5,
+ debug = true,
+ version = "2.1.0",
+ debounceMs = 2000,
+ ),
+)
+```
+
+> **No screen recording.** Unlike the Flutter SDK, the Android library does not record video. The `screenCapture`, `capturePixelRatio`, `maxBufferFrames`, and `fps` options are accepted for API parity but have no effect.
+
+## Logs & Actions
+
+Every captured exception ships with the last ~10 seconds of session context, attached to a `sessionRecordings` entry on the wire — the same shape the Flutter SDK uses (minus the video chunks). Two independent rolling buffers — **logs** and **actions** — are kept in memory, each capped at 200 entries by default.
+
+### Logs
+
+Every `println` and any other write to `System.out` / `System.err` is mirrored into the log buffer. Console output behaves normally; it just gets a copy.
+
+Calls that go straight to `android.util.Log` bypass `System.out` and are **not** captured automatically. To pick up Logcat lines, install a Timber tree (or any other logger) that calls `TracewayClient.instance?.recordLog(message, level)`:
+
+```kotlin
+import com.tracewayapp.traceway.TracewayClient
+import timber.log.Timber
+
+Timber.plant(object : Timber.Tree() {
+ override fun log(priority: Int, tag: String?, message: String, t: Throwable?) {
+ TracewayClient.instance?.recordLog(message, level = priority.toLogLevel())
+ }
+})
+```
+
+### Actions
+
+Three kinds of actions are collected:
+
+- **Network** — every HTTP request routed through an OkHttp client with `TracewayOkHttpInterceptor` installed (method, URL, status, duration, request/response byte counts). Catches Retrofit, Coil, Glide-via-OkHttp, and your own usage:
+
+ ```kotlin
+ val client = OkHttpClient.Builder()
+ .addInterceptor(TracewayOkHttpInterceptor())
+ .build()
+ ```
+
+ For HTTP clients that aren't OkHttp, record events manually:
+
+ ```kotlin
+ TracewayClient.instance?.recordNetworkEvent(
+ NetworkEvent(method = "GET", url = "https://...", durationMs = 42L, statusCode = 200)
+ )
+ ```
+
+- **Navigation** — activity `push` / `pop` transitions, recorded automatically once `Traceway.init(...)` runs (the SDK registers an `Application.ActivityLifecycleCallbacks` for you). No wiring needed on your side.
+
+- **Custom** — anything your app records explicitly:
+
+ ```kotlin
+ Traceway.recordAction(
+ category = "cart",
+ name = "add_item",
+ data = mapOf("sku" to "SKU-123", "qty" to 2),
+ )
+ ```
+
+### Wire shape
+
+Logs and actions are sent to the backend inside the same `sessionRecordings` entry that the Flutter SDK uses for video — they're stored under separate `logs` and `actions` arrays. Each recording carries `startedAt` and `endedAt` ISO 8601 timestamps so the backend can align events on a timeline (`offsetIntoVideoMs = event.timestamp − recording.startedAt`):
+
+```json
+{
+ "sessionRecordings": [
+ {
+ "exceptionId": "...",
+ "startedAt": "2026-04-28T14:30:53.011Z",
+ "endedAt": "2026-04-28T14:31:02.314Z",
+ "logs": [
+ {"type": "log", "timestamp": "2026-04-28T14:30:54.508Z", "level": "info", "message": "user tapped pay"}
+ ],
+ "actions": [
+ {"type": "navigation", "action": "push", "from": "/", "to": "/cart", "timestamp": "2026-04-28T14:30:53.011Z"},
+ {"type": "network", "method": "GET", "url": "...", "statusCode": 200, "durationMs": 86, "timestamp": "2026-04-28T14:30:54.422Z"},
+ {"type": "custom", "category": "cart", "name": "add_item", "data": {"sku": "SKU-1"}, "timestamp": "2026-04-28T14:30:54.605Z"}
+ ]
+ }
+ ]
+}
+```
+
+`startedAt` and `endedAt` come from the timestamp range of the buffered events. A session recording entry is created for every captured exception that has any timeline data.
+
+### Disabling channels
+
+Each channel can be turned off individually via `TracewayOptions`:
+
+```kotlin
+Traceway.init(
+ application = this,
+ connectionString = "your-token@https://traceway.example.com/api/report",
+ options = TracewayOptions(
+ captureLogs = false, // println / System.out / System.err
+ captureNetwork = false, // OkHttp interceptor events
+ captureNavigation = false, // Activity push / pop
+ ),
+)
+```
+
+## What Gets Captured Automatically
+
+`Traceway.init(...)` sets up capture for the following sources with no additional configuration:
+
+- **Uncaught Java/Kotlin exceptions** on every thread, via `Thread.setDefaultUncaughtExceptionHandler`
+- **View click handler throws** — uncaught exceptions inside `View.OnClickListener`, `AlertDialog` button handlers, and similar UI callbacks
+- **Background thread throws** — anything that escapes a `Thread`'s `run()` body
+- **Main `Handler.post` throws** — async exceptions on the main looper, caught by the default uncaught-exception handler
+- **Activity lifecycle transitions** — `push` / `pop` recorded as navigation actions
+
+## Test Your Integration
+
+Add a button that throws an exception to verify everything is wired up:
+
+```kotlin
+Button(this).apply {
+ text = "Send Test Error"
+ setOnClickListener {
+ throw RuntimeException("Test error from Traceway")
+ }
+}
+```
+
+Tap the button and check your Traceway dashboard to verify the error appears with its full stack trace.
+
+## Platform Support
+
+| Platform | Error Tracking | Screen Recording |
+|----------|----------------|------------------|
+| Android (API 21+) | Yes | No |
+
+For Flutter apps that need cross-platform error tracking (and screen recording on iOS / Android / macOS), use the [Flutter SDK](/client/flutter?sdk=flutter) instead — it ships the same wire format so a single Traceway backend handles both.
diff --git a/docs/public/android.png b/docs/public/android.png
new file mode 100644
index 00000000..b5f0b5da
Binary files /dev/null and b/docs/public/android.png differ
diff --git a/docs/theme.config.jsx b/docs/theme.config.jsx
index 155f097d..013e4424 100644
--- a/docs/theme.config.jsx
+++ b/docs/theme.config.jsx
@@ -24,6 +24,7 @@ const SDK_VISIBILITY = {
nextjs: "js-nextjs",
symfony: "php-symfony",
flutter: "flutter",
+ android: "android",
};
export default {
diff --git a/frontend/src/lib/components/framework-combobox.svelte b/frontend/src/lib/components/framework-combobox.svelte
index bc4df051..bff0fbb5 100644
--- a/frontend/src/lib/components/framework-combobox.svelte
+++ b/frontend/src/lib/components/framework-combobox.svelte
@@ -36,6 +36,7 @@
{ value: 'cloudflare', label: 'Cloudflare', description: 'Cloudflare Workers (OTLP Traces)', group: 'Backend' },
{ value: 'opentelemetry', label: 'OpenTelemetry', description: 'Vendor-neutral observability', group: 'Backend' },
{ value: 'flutter', label: 'Flutter', description: 'Mobile UI framework', group: 'Mobile' },
+ { value: 'android', label: 'Android', description: 'Native Android (Kotlin/Java)', group: 'Mobile' },
] as const;
const selectedFrameworkLabel = $derived(getFrameworkLabel(value));
diff --git a/frontend/src/lib/components/framework-icon.svelte b/frontend/src/lib/components/framework-icon.svelte
index c95dad54..676fd461 100644
--- a/frontend/src/lib/components/framework-icon.svelte
+++ b/frontend/src/lib/components/framework-icon.svelte
@@ -58,6 +58,8 @@
<img src="/symfony.png" alt="Symfony" class={className} />
{:else if framework === 'flutter'}
<img src="/flutter.png" alt="Flutter" class={className} style="object-fit: contain;" />
+{:else if framework === 'android'}
+ <img src="/android.png" alt="Android" class={className} style="object-fit: contain;" />
{:else}
<img src="/custom.png" alt="Custom" class={className} />
{/if}
diff --git a/frontend/src/lib/state/projects.svelte.ts b/frontend/src/lib/state/projects.svelte.ts
index 3e8ff997..6bf30a83 100644
--- a/frontend/src/lib/state/projects.svelte.ts
+++ b/frontend/src/lib/state/projects.svelte.ts
@@ -1,9 +1,9 @@
import { api } from '$lib/api';
import { authState } from './auth.svelte';
-export type Framework = 'gin' | 'fiber' | 'chi' | 'fasthttp' | 'stdlib' | 'custom' | 'react' | 'svelte' | 'vuejs' | 'nextjs' | 'nestjs' | 'express' | 'remix' | 'jquery' | 'hono' | 'cloudflare' | 'opentelemetry' | 'symfony' | 'flutter';
+export type Framework = 'gin' | 'fiber' | 'chi' | 'fasthttp' | 'stdlib' | 'custom' | 'react' | 'svelte' | 'vuejs' | 'nextjs' | 'nestjs' | 'express' | 'remix' | 'jquery' | 'hono' | 'cloudflare' | 'opentelemetry' | 'symfony' | 'flutter' | 'android';
-export const FRONTEND_FRAMEWORKS: Framework[] = ['react', 'svelte', 'vuejs', 'jquery', 'flutter'];
+export const FRONTEND_FRAMEWORKS: Framework[] = ['react', 'svelte', 'vuejs', 'jquery', 'flutter', 'android'];
export const JS_FRAMEWORKS: Framework[] = ['react', 'svelte', 'vuejs', 'nextjs', 'nestjs', 'express', 'remix', 'jquery'];
export const FRAMEWORK_LABELS: Record<Framework, string> = {
@@ -26,9 +26,10 @@ export const FRAMEWORK_LABELS: Record<Framework, string> = {
opentelemetry: 'OpenTelemetry',
symfony: 'Symfony',
flutter: 'Flutter',
+ android: 'Android',
};
-export const MOBILE_FRAMEWORKS: Framework[] = ['flutter'];
+export const MOBILE_FRAMEWORKS: Framework[] = ['flutter', 'android'];
export function getFrameworkLabel(fw: Framework): string {
return FRAMEWORK_LABELS[fw] ?? fw;
diff --git a/frontend/src/lib/utils/framework-code.ts b/frontend/src/lib/utils/framework-code.ts
index 53fee1b1..6956b345 100644
--- a/frontend/src/lib/utils/framework-code.ts
+++ b/frontend/src/lib/utils/framework-code.ts
@@ -40,6 +40,8 @@ export function getInstallCommand(framework: Framework): string {
return '';
case 'flutter':
return 'flutter pub add traceway';
+ case 'android':
+ return 'implementation("com.tracewayapp:traceway:1.0.0")';
case 'custom':
default:
return base;
@@ -301,6 +303,22 @@ void main() {
);
}`;
+ case 'android':
+ return `import android.app.Application
+import com.tracewayapp.traceway.Traceway
+import com.tracewayapp.traceway.TracewayOptions
+
+class MyApp : Application() {
+ override fun onCreate() {
+ super.onCreate()
+ Traceway.init(
+ application = this,
+ connectionString = "${connectionString}",
+ options = TracewayOptions(version = "1.0.0"),
+ )
+ }
+}`;
+
case 'custom':
default:
return `package main
@@ -340,6 +358,10 @@ class TestController
if (framework === 'flutter') {
return `// Trigger a test error
throw StateError('Test error from Traceway integration');`;
+ }
+ if (framework === 'android') {
+ return `// Trigger a test error
+throw RuntimeException("Test error from Traceway integration")`;
}
if (framework && isJsFramework(framework)) {
return `// Trigger a test error
@@ -361,6 +383,15 @@ TracewayClient.instance?.captureException(
Exception('Test error'),
StackTrace.current,
);`;
+ }
+ if (framework === 'android') {
+ return `import com.tracewayapp.traceway.Traceway
+
+try {
+ riskyOperation()
+} catch (e: Throwable) {
+ Traceway.captureException(e)
+}`;
}
if (framework && isJsFramework(framework)) {
switch (framework) {
@@ -430,6 +461,7 @@ export function getFrameworkLabel(framework: Framework): string {
opentelemetry: 'OpenTelemetry',
symfony: 'Symfony',
flutter: 'Flutter',
+ android: 'Android',
};
return labels[framework] || framework;
}
@@ -440,5 +472,6 @@ export function getCodeLanguage(framework: Framework): 'go' | 'javascript' | 'ba
if (framework === 'hono') return 'javascript';
if (framework === 'cloudflare') return 'javascript';
if (framework === 'flutter') return 'javascript'; // closest to Dart syntax highlighting
+ if (framework === 'android') return 'javascript'; // closest to Kotlin syntax highlighting
return isJsFramework(framework) ? 'javascript' : 'go';
}
diff --git a/frontend/static/android.png b/frontend/static/android.png
new file mode 100644
index 00000000..b5f0b5da
Binary files /dev/null and b/frontend/static/android.png differ