Instrumenting bitdrift in the Wikipedia app: A step-by-step guide for Android Devs

In this series, we’ll walk through practical examples of using bitdrift in production mobile apps. Whether you’re new to mobile observability or a seasoned dev exploring bitdrift for the first time, this guide will help you get started fast. We’ll begin with core concepts like basic setup, networking, and custom logging—and cover features like User Journeys, Funnels, and Crash Reporting in future posts. For this post, we’re using The official Wikipedia app for Android to demonstrate integration in a real-world context. Like most teams, you're probably not working with a greenfield app, so we’re skipping the "Hello World" examples and diving straight into a mature codebase. Working with iOS? Check out the iOS guide here → For those who prefer to view the instrumented code, it is available here. This code contains all the instrumentation that we will cover in this blog series, which is a work in progress and therefore subject to change. While writing this blog post, we used Android Studio Meerkat Feature Drop (2024.3.2 Patch 1) with Gradle 8.8.0, and bitdrift Capture 0.17.29. Heads up: You’ll need an API key to get started. Drop us a note at info@bitdrift.io and we’ll send one your way. We assume you already forked the Wikipedia app and are ready to edit the code and build with Android Studio. You’ll need the app running in an emulator to complete the exercise. If you’re ready, let’s get to it!

Basic Instrumentation

Basic instrumentation requires only a few minor code changes. First, we need to configure bitdrift's Maven Repository. Find the settings.gradle.kts file in the project root and add the repository to the dependencyResolutionManagement block.

kotlin
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        mavenLocal()
        maven(url = "https://dl.bitdrift.io/sdk/android-maven") {
            content {
                includeGroup("io.bitdrift")
            }
        }
    }
}

Next, integrate the Capture SDK into your app’s source code. Locate the build.gradle file in the app directory, and update the dependencies block.

kotlin
dependencies {
    implementation libs.capture.sdk
}

The Wikipedia app uses Version Catalogs, so locate the libs.versions.toml file in the gradle folder and update the [versions] and [libraries] blocks.

kotlin
[versions]
captureSdk = "0.17.29"

[libraries]
capture-sdk = { module = "io.bitdrift:capture", version.ref = "captureSdk" }

Finally, initialize the SDK as early as possible in the app’s lifecycle. Locate the WikipediaApp.kt file and add the required imports. Then update the onCreate function to include Logger.start().

kotlin
import io.bitdrift.capture.Capture.Logger
import io.bitdrift.capture.providers.session.SessionStrategy


override fun onCreate() {
        super.onCreate()

        Logger.start(
            apiKey = "your-api-key",
            sessionStrategy = SessionStrategy.fixed()
        )
. . .
}

We are using a fixed() session strategy. This is commonly used in production, but is also helpful for testing. It creates a new session every time the app restarts—making it easier to track sessions during development.

Networking and Custom Logging

One of our goals with this post was to demonstrate that instrumenting even a mature, production app is surprisingly easy. We were going to save networking and logging for another post, but since we got through the basic instrumentation so quickly, let’s just get it done now! The Wikipedia app uses OkHttp under the hood, which means we can take full advantage of bitdrift’s auto-instrumentation. Easy peasy. Open the settings.gradle.kts file in the project root. This is where we added the bitdrift maven repository earlier. Add the same repository to the pluginManagement block.

kotlin
pluginManagement {
    repositories {
        google()
        mavenCentral()
        gradlePluginPortal()
        maven(url = "https://dl.bitdrift.io/sdk/android-maven")
    }
}

Next, open the app/build.gradle file. To enable the capture plugin at build time, add it to the plugins block.

kotlin
plugins {
    id 'com.android.application'
    id 'io.bitdrift.capture-plugin' version '0.17.29'
    alias(libs.plugins.compose.compiler)
}

At the end of the app/build.gradle file, add this custom DSL.

kotlin
bitdrift {
    instrumentation {
        automaticOkHttpInstrumentation = true
    }
}

Networking done! On to logging … bitdrift provides a plugin for Timber, but the Wikipedia app uses a custom logging utility org.wikipedia.util.log.L. Fortunately, adapting it is easy. We just need to modify the L class to forward log messages to bitdrift alongside Android’s native Log calls. Here’s an example.

kotlin
private val LEVEL_V: LogLevel = object : LogLevel() {
    override fun logLevel(tag: String?, msg: String?, t: Throwable?) {
        Log.v(tag, msg, t)
        Logger.logTrace(
            fields = mapOf("tag" to tag.orEmpty()),
            throwable = t
        ) {
            msg.orEmpty()
        }
    }
}

Since Wikipedia has different methods for each verbosity level, we need to do the same for each one, as exemplified here. That’s it! Basic instrumentation, networking, and custom logs are all configured! Now, all we need to do is build our app. But first, let’s create a workflow to capture sessions.

Capture sessions with a workflow

Log in to your bitdrift account and replicate the steps from the video below, or continue reading for written instructions. In the left-hand navigation, hit the “+” button to create a new exploration. This will create a “New Exploration” folder and a blank workflow. At the top left of the canvas, hit the dropdown and check the “Any App” checkbox under Android. To the right of this dropdown, you will see a Hand Tool button (for moving things around the canvas) and two more dropdown menus. The first contains matchers, and the second includes actions. From the Matchers dropdown, select Default Events and click anywhere on the canvas to add the Default Events matcher to the workflow. Hover over the Start node and you’ll see a “+” appear on the right edge. Click and drag this to connect the start node to the left side of your Default Events node. Now, double-click the default event to open the settings panel. From the parameters dropdown, select “Orientation Change” and hit Save. Now, from the Actions dropdown, select the "Record Session" action and drop it onto the canvas. A menu will appear, prompting you to enter a name. Enter “SDK Started” and hit Save. Then, create a link from your Default Events node to your Record Session node. Your workflow should resemble Figure 1. If it does, click the green Deploy Workflow button.

Now let’s build the Wikipedia app! (If you encounter any issues at this point, please don’t hesitate to reach out to us in our public Slack channel.) Once the app is built and running in the emulator, it will connect to the bitdrift control plane, and bitdrift will push the workflow to your emulator. Take a minute or two to browse the app, read an interesting article, explore some Places, and be sure to change the orientation a few times as you go. Now go back to your browser and view your Exploration. Ta-dah! You should see a new session listed below the workflow. Click on it to view the Session Timeline. Now, let’s take a tour of your session by following the steps in the video below.

Wrapping Up

You’ve just taken a production-grade app – The Official Wikipedia app for Android – and instrumented it with the bitdrift SDK, including all of the existing network calls and custom logs. You also pushed your first workflow and captured your first session: no dummy apps, no shortcuts. Look out for the following posts in this series, where we’ll cover topics like Crash Reporting, Funnels, and User Journeys. Until then, feel free to experiment with what you’ve built so far. Try editing your workflow to trigger on different SDK events, or explore the Session Timeline to see how bitdrift structures and surfaces the data. If you have questions or encounter issues, we’d be happy to help. Drop into our public Slack channel or email us at info@bitdrift.io. Happy instrumenting 🚀