Skip to main content

Installation

note

This page documents Bugsee Android SDK 7.x. For the previous release, see the 6.x installation guide.

Bugsee ships as a core artifact plus one extension module per optional capability, and requires the Gradle plugin, which performs build-time bytecode and Kotlin-compiler instrumentation (APM operation dispatch, log capture, OkHttp injection, Compose secure modifier, etc.). Without the plugin, several features stop working or require manual wiring.

1. Apply the Bugsee Gradle plugin​

Apply the plugin to your application module. Library modules are not instrumented.

// settings.gradle.kts (root)
pluginManagement {
    repositories {
        gradlePluginPortal()
        mavenCentral()
        google()
    }
}

// app/build.gradle.kts
plugins {
    id("com.android.application")
    id("org.jetbrains.kotlin.android")
    id("com.bugsee.android.gradle") version "<plugin-version>"
}

bugsee {
    appToken("<your-app-token>")
    // ndk { enabled.set(true) }      // upload NDK symbols
    // instrumentation { /* ... */ }  // per-feature toggles
}

What the plugin does at build time:

  • Injects BugseeLogAdapter into every android.util.Log.* call site.
  • Injects BugseeOkHttpInterceptor into every OkHttpClient.Builder.build().
  • Wraps every android.net.http.HttpEngine.Builder.build() (Android 14+).
  • Injects BugseeThreadAdapter.registerThread() at the start of every Runnable.run() / Thread.run() (used by the native crash reporter).
  • Injects APM operation dispatch (db.*, file.*, http.client spans) and optional main-thread-misuse pre-checks.
  • Instruments Jetpack Compose touch dispatch and auto-applies Modifier.bugseeSecure() to password TextFields.
  • Auto-adds matching bugsee-android-* extension modules when it detects OkHttp, Ktor 2/3, Cronet, or Compose in your dependency graph.
  • Injects BUILD_UUID into the merged manifest and uploads mapping / NDK symbols on assemble/bundle.

Each capability can be toggled via the bugsee { instrumentation { ... } } block. See the Gradle plugin reference for details.

Plugin 4.x is paired with SDK 7.x

The Gradle plugin and the runtime library are versioned independently but must be matched by line: SDK 7.x requires plugin 4.x, and plugin 3.x requires SDK 6.x. Mixing the two lines will fail at build or runtime.

Pin the plugin to a specific version rather than a floating range. See the Gradle plugin requirements for the current supported plugin version.

2. Add SDK artifacts​

With the Gradle plugin applied, the core com.bugsee:bugsee-android artifact is pulled automatically as soon as any Bugsee dependency (including an extension module) is in your build, and dependency-driven extensions (OkHttp, Ktor 2/3, Cronet, Compose) are auto-installed when the plugin detects the matching third-party library.

The three extensions that aren't dependency-driven — feedback, NDK, and leak — are enabled via DSL toggles in the bugsee { … } block. Setting the toggle is all you need; the plugin pulls in the artefact at the same version as itself so extension and core versions never drift apart:

bugsee {
    appToken("<your-app-token>")

    // In-app feedback messenger UI (default: off)
    feedback.set(true)

    // Native (NDK) crash capture (default: off)
    ndk {
        enabled.set(true)
    }

    // Memory & thread leak detection (default: off)
    leak {
        enabled.set(true)
    }
}

In this typical setup, your dependencies { … } block needs no Bugsee entries at all — the plugin handles core and extensions for you.

Pinning a specific extension version​

When you need to lock an extension to a specific version (for example, to downgrade against a regression while waiting for a fix), declare it explicitly alongside the DSL toggle. The explicit declaration wins:

dependencies {
    implementation("com.bugsee:bugsee-android-feedback:7.0.0")
}

The same pinning rule applies to the core: declaring com.bugsee:bugsee-android yourself on any configuration suppresses the plugin's auto-pull and your version wins.

Opting out of the core auto-pull​

To opt out of the core SDK auto-pull entirely — for example when shipping the core from a manual classpath path or a locally-published artefact — set the top-level sdkAutoLoad flag to false:

bugsee {
    sdkAutoLoad.set(false)
}

The dynamic-version range used for the auto-pulled core is bounded to the next major version above the plugin's sdk-min-version (currently [7.1.0, 8.0.0)), so you pick up any newer compatible 7.x release automatically.

The full list of dependency-driven auto-installs lives on the Gradle plugin page.

Extensions auto-register via their own ContentProvider; no runtime wiring is needed. Ktor and Cronet still require per-client wiring at call sites (see network).

info

com.bugsee:bugsee-android-okhttp covers OkHttp 3 and 4 (and any library that transitively uses them, including Picasso and Retrofit). OkHttp 2 is no longer supported.

3. Initialize the SDK​

7.0 supports two initialization paths. Pick one.

Option A — Manifest auto-launch (recommended)​

Add the app token as <meta-data> inside <application>. The SDK launches automatically at process start via BugseeInitProvider. You do not need an Application subclass and you do not need to call Bugsee.launch(...).

<application ...>
    <meta-data
        android:name="com.bugsee.app-token"
        android:value="@string/bugsee_app_token" />
</application>

Any SDK option can also be set via manifest metadata — every Options.* constant doubles as a manifest key:

<meta-data android:name="com.bugsee.option.detect.crash-ndk"
           android:value="true" />
<meta-data android:name="com.bugsee.option.capture.breadcrumbs"
           android:value="true" />
<meta-data android:name="com.bugsee.option.config.duration"
           android:value="120" />

For enum-typed options, pass the enum value name as a string (e.g. "High" for FrameRate.High). See the full key table in the configuration reference.

Option B — Programmatic launch​

If no token is declared in the manifest, call one of the Bugsee.launch(...) overloads. The context is auto-discovered via BugseeInitProvider.

If you do keep the token in the manifest but still want to launch from code (for example to compute options at runtime), disable the manifest auto-launch by adding the com.bugsee.auto-init meta-data, set to false:

<application ...>
    <meta-data
        android:name="com.bugsee.app-token"
        android:value="@string/bugsee_app_token" />

    <!-- Auto-init disabled — launch from code instead. -->
    <meta-data
        android:name="com.bugsee.auto-init"
        android:value="false" />
</application>
import com.bugsee.library.Bugsee;
import com.bugsee.library.contracts.options.Options;

// Simplest form — context resolved automatically.
Bugsee.launch("<your-app-token>");

// Explicit context.
Bugsee.launch(context, "<your-app-token>");

// With options (keys from com.bugsee.library.contracts.options.Options).
Map<String, Serializable> options = new HashMap<>();
options.put(Options.Duration, 60);
options.put(Options.CaptureNetwork, true);
Bugsee.launch(context, "<your-app-token>", options);

// With completion callback (may be invoked on a background thread).
Bugsee.launch(context, "<your-app-token>", options, success -> {
    // success == true on launch, false on failure
});
Manifest and programmatic options are mutually exclusive, not merged

The two initialization paths do not combine on a per-key basis. Whichever path launches the SDK first wins and runs with its own options object only. When you pass a Map to Bugsee.launch(...), that map is the complete option set for the session — any option you leave out of the map falls back to its registered default, not to the value you declared in AndroidManifest.xml. Treat the programmatic map as a full override, not a patch on top of the manifest. The same model is described in the configuration overview.

For stop(), relaunch(), and other lifecycle controls, see lifecycle.

4. ProGuard / R8​

Each module ships its own consumer ProGuard rules inside the AAR. No manual rules are required.

5. Verify​

Build and run the app. On next launch, the Bugsee floating report button should appear. Trigger a test report (shake the device, or call Bugsee.showReportDialog()) to confirm end-to-end delivery to your dashboard.

Next:

Found an issue, typo, or wrong statement on this page? Report it now →