Instrumenting bitdrift in the Wikipedia app: A step-by-step guide for iOS 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 iOS app 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 Android? Check out the Android 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 Xcode 16.4 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 XCode. You’ll need the app running in a simulator to complete the exercise. If you’re ready, let’s get to it!

Instrumentation

Instrumentation requires only minor code changes to a couple of files. First, we need to update our package dependencies. Go to File > Add Package Dependencies, search for github.com/bitdriftlabs/capture-ios.git, and click Add Package. When prompted to choose package products, make sure you add Capture and CaptureCocoaLumberjack to your desired build target. You will not need CaptureSwiftyBeaver for this exercise. Before adding the code below, set BITDRIFT_API_KEY as an environment variable in your local scheme: Product > Scheme > Edit Scheme > Run (left nav) > Environment Variables. Open AppDelegate.swift and add the following imports.

swift
import Capture
import CaptureCocoaLumberjack

Then update the application(_:didFinishLaunchingWithOptions:) function and ensure that Logger.start() is the first thing that starts.

swift
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {

let apiKey = ProcessInfo.processInfo.environment["BITDRIFT_API_KEY"] ?? ""

Logger.start(
    withAPIKey: apiKey,
    sessionStrategy: .fixed(),
  )?
  .enableIntegrations(
    [.urlSession(), .cocoaLumberjack()], disableSwizzling: true)

. . .

}

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

You might have noticed that in the Logger.start() call, we enabled two integrations:

• urlSession() — Automatically instruments HTTP traffic from URLSession
• cocoaLumberjack() — Forwards all logs emitted by CocoaLumberjack

But why disable swizzling? The default URLSession integration uses method swizzling for automatic instrumentation. However, swizzling only works if Logger.start() runs before any URLSession instance is created. In the Wikipedia app, URLSession is initialized earlier; therefore, we disabled swizzling and opted for the alternative, swizzling-free integration method. To support this, we need to update Session.swift. Locate the getURLSession() function and modify it as follows:

swift
import Capture

private static func getURLSession(with permanentCacheController: PermanentCacheController? = nil, delegate: SessionDelegate) -> URLSession {
    let config = URLSessionConfiguration.default
    config.httpCookieStorage = Session.defaultCookieStorage
    config.urlCache = permanentCacheController?.urlCache ?? URLCache.shared
    return URLSession(
                instrumentedSessionWithConfiguration: config,
                delegate: delegate,
                delegateQueue: delegate.delegateQueue
            )
}

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 simulator, it will connect to the bitdrift control plane, and bitdrift will push the workflow to your simulator. 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 iOS app – 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 🚀