SDK Quickstart¶

Pre-requisites¶

In order for the SDK to operate, you need to get an API key for your apps.

Contact us at info@bitdrift.io to get an API Key.

Installation¶

Android¶

Info

The Android SDK requires a minimum API level of 21.

The Capture SDK is distributed as an .aar that is available via the bitdrift Maven repo. Configure it in your settings.gradle file:

Gradle (Kotlin)Gradle (Groovy)

Kotlin

repositories {
  maven(url = "https://dl.bitdrift.io/sdk/android-maven") {
    content {
      includeGroup("io.bitdrift")
    }
  }
}

Groovy

repositories {
  maven {
    url 'https://dl.bitdrift.io/sdk/android-maven'
    content {
      includeGroup 'io.bitdrift'
    }
  }
}

Once the repository is configured, simply add the following line to the dependencies in your build.gradle file:

Gradle (Kotlin)Gradle (Groovy)

Kotlin

dependencies {
  implementation("io.bitdrift:capture:<version>")
}

Groovy

dependencies {
  implementation 'io.bitdrift:capture:<version>'
}

If your project uses Version Catalogs, you can remove the :version component from your build.gradle file and manage the Capture SDK version in your libs.versions.toml file.

TOML

[versions]
captureSdk = <version>

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

For the full list of available Android Capture SDK releases visit Android releases page.

iOS¶

Info

The iOS SDK requires a minimum iOS version of 15.

Info

The SDK exposes all of its interfaces to Swift code while a portion of it is available to Objective-C code as well.

The Capture SDK is distributed as static library packaged in an xcframework and can be integrated into Xcode directly. The provided archive contains the static library for both iOS devices and simulator.

For the full list of available iOS Capture SDK releases visit iOS releases page.

Swift Package Manager¶

The Capture SDK can be integrated using Swift Package Manager (SPM) by utilizing the bitdriftlabs/capture-ios Swift PM-compatible Git repository.

Swift

.package(url: "https://github.com/bitdriftlabs/capture-ios.git", from: "<version>")

CocoaPods¶

The Capture SDK can be integrated via CocoaPods by adding the BitdriftCapture pod to your project. Include the following statement in your Podfile:

Ruby

target 'YourApp' do
  pod 'BitdriftCapture'
end

Despite the pod being named BitdriftCapture, it is important to note that the Swift module is referred to as Capture.

React Native¶

Info

The React Native SDK requires a minimum iOS version of 15 and Android API level of 21.

The Capture SDK can be added to your React Native project by using the @bitdrift/react-native package from npm: https://www.npmjs.com/package/@bitdrift/react-native

npm

Bash

npm install @bitdrift/react-native

On iOS, the React Native SDK is incompatible with the use_frameworks! :linkage => :static option in your Podfile or via the Expo config as this prevents internal Objective-C bridging headers from being generated.

Electron¶

The Capture SDK can be added to your Electron project by using the @bitdrift/electron package from npm: https://www.npmjs.com/package/@bitdrift/electron

npm

Bash

npm install @bitdrift/electron

Configuration¶

Once the dependency has been set up, the logger can be started in the following way:

Android (Kotlin)Android (Java)iOS (Swift)iOS (Objective-C)React NativeElectron

Kotlin

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

Logger.start(
  apiKey = "<your-api-key>",
  sessionStrategy = SessionStrategy.ActivityBased(),
)

Java

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

Logger.start(
  "<your-api-key>",
  new SessionStrategy.ActivityBased()
);

Swift

import Capture

Logger.start(
  withAPIKey: "<your-api-key>",
  sessionStrategy: .activityBased()
)

Info

It's recommended that you initialize the SDK as part of your application's application(_:willFinishLaunchingWithOptions:) or application(_:didFinishLaunchingWithOptions:) methods. This allows the SDK to observe system events such as didFinishLaunchingNotification, which power some of the SDK's out-of-the-box events.

Objective-C

#import <Capture/Capture.h>

[CAPLogger
  configureWithAPIKey:@"<your-api-key>"
  sessionStrategy:[CAPSessionStrategy activityBased]
];

Info

It's recommended that you initialize the SDK as part of your application's application(_:willFinishLaunchingWithOptions:) or application(_:didFinishLaunchingWithOptions:) methods. This allows the SDK to observe system events such as didFinishLaunchingNotification, which power some of the SDK's out-of-the-box events.

JavaScript

import { init, SessionStrategy } from '@bitdrift/react-native';

init("<your-api-key>", SessionStrategy.Activity);

See the Configuration section for information about how to configure for different React Native environments.

Info

It is recommended to initialize the SDK as soon as possible to capture all the necessary data.

JavaScript

import { init, SessionStrategy } from '@bitdrift/electron';

init("<your-api-key>", SessionStrategy.Activity);

The SDK should be initialized in the main process.

See the SDK Session Management section for information about how to configure a session strategy.

Tip

See the Fatal Issues & Crashes section for instructions on how to capture these events automatically.

Usage¶

The SDK will automatically begin collecting data from the device without any extra steps, responding to lifetime events and performing periodic collection of data.

To provide custom logs to the system, the SDK can be used as a logger:

Android (Kotlin)Android (Java)iOS (Swift)iOS (Objective-C)React NativeElectron

Kotlin

// Log line with LogLevel of Info
Logger.logInfo(mapOf("key" to "value")) { "Hello world!!" }

Java

// Log line with LogLevel of Info
Logger.logInfo(Collections.singletonMap("key", "value"), () -> "Info log");

Swift

// Log line with LogLevel of Info
Logger.logInfo("Hello world!", fields: ["key": "value"])

Objective-C

// Log line with LogLevel of Info
[CAPLogger logInfo:@"Hello world!" fields:@{@"key": @"value"}];

JavaScript

import { info } from '@bitdrift/react-native';

// Log line with LogLevel of Info
info('Hello world!', { key: 'value' });

JavaScript

import { info } from '@bitdrift/electron';

// Log line with LogLevel of Info
info('Hello world!', { key: 'value' });

The logging calls must be performed on the main process.

Read more about other configuration options and usages in our Features page.

Binaries & Symbolication¶

Both the Android and iOS SDK wraps a common Rust-based core, which is packaged differently depending on the platform.

Android¶

The packaged .aar provides per-architecture shared libraries that are loaded at runtime and consumed via JNI. The packaged .so files have undergone heavy optimizations and stripping of symbols to make them suitable for direct integration into apps with minimal impact of binary size.

A consequence of this stripping is that should a native crash occur, crash handlers won't have any way to symbolicate the native crash. To provide a way to understand these crashes, NDK shared object mappings are provided as part of the capture-*-symbols.tar archive which can be found adjacent to the .aar in the releases page. These can be uploaded to relevant crash handlers to symbolicate native crashes.

iOS¶

The iOS SDK is distributed as a static library, which is linked statically into the final app. This differs from the Android packaging in that most link-time optimizations (like dead code stripping) must be performed at the app linking stage, and so the distributed library is much larger. Symbols have not been stripped in the static library, and so they should be folded into the final app build, requiring no further steps to ensure that crashes are symbolicated.