---
title: "Instrumenting bitdrift in the Wikipedia app: A step-by-step guide for Android Devs"
slug: "hands-on-wikipedia-android"
tags:
- "observability"
- "mobile"
blurb: "Welcome to the first post in our bitdrift hands-on series!"
cover:
url: "/assets/posts/hands-on-wikipedia-android/feature-hero-desktop@1x.webp"
alt: "bitdrift hands-on series image 1"
socialThumbnail:
url: "/assets/posts/hands-on-wikipedia-android/feature-hero-desktop@1x.webp"
alt: "bitdrift hands-on series image 1"
author:
- "iain"
publishedDate: "2025-08-08T14:00:00.000Z"
modifiedDate: "2025-08-08T14:00:00.000Z"
---
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](https://github.com/wikimedia/apps-android-wikipedia) 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 →](https://blog.bitdrift.io/post/hands-on-wikipedia-ios)
For those who prefer to view the instrumented code, it is available [here](https://github.com/wikimedia/apps-android-wikipedia/compare/main...iainfinlayson:wikipedia-android-bitdrift:bitdrift-blog-2025-08-08). 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 AGP 8.8.0, and bitdrift Capture 0.17.29.
If you don't have access to a bitdrift account, head on over to our website and [sign up for free](https://bitdrift.io/signup).
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
**Update (Sept 2025):** bitdrift SDK artifacts are now published to Maven Central. You can see the updated instrumentation code [here](https://github.com/wikimedia/apps-android-wikipedia/compare/main...iainfinlayson:wikipedia-android-bitdrift:bitdrift-blog-2025-08-08-update).
.
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](https://docs.bitdrift.io/sdk/integrations#timber-android), 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](https://github.com/iainfinlayson/wikipedia-android-bitdrift/blob/main/app/src/main/java/org/wikipedia/util/log/L.kt).
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](https://communityinviter.com/apps/bitdriftpublic/bitdrifters).) 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](https://docs.bitdrift.io/product/timeline-features). 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](https://communityinviter.com/apps/bitdriftpublic/bitdrifters) or email us at [info@bitdrift.io](mailto:info@bitdrift.io).
Happy instrumenting 🚀