--- title: SDK Quickstart --- # SDK Quickstart ## Pre-requisites In order for the SDK to operate, you will need an SDK key. bitdrift administrators can create SDK keys by browsing to Company Settings under their profile. If you do not have a bitdrift account you can sign up for a free trial at [bitdrift.io](https://bitdrift.io/signup). When you first launch bitdrift, Chippy will create an SDK key for you, along with the code required to instrument your app. If you don't complete the instrumention process during signup, you can always pick up your work with Chippy at anytime by returning to the [signup page](https://bitdrift.io/signup). ## Installation ### Android [Maven Central Version](https://central.sonatype.com/artifact/io.bitdrift/capture){:target="_blank"} [GitHub Release](https://github.com/bitdriftlabs/capture-sdk/releases){:target="_blank"} !!! info The Android SDK requires a minimum API level of 23. The Capture SDK is available via maven central, simply add the following line to the dependencies in your `build.gradle` file: === "Gradle (Kotlin)" ```kotlin dependencies { implementation("io.bitdrift:capture:") } ``` === "Gradle (Groovy)" ```groovy dependencies { implementation 'io.bitdrift:capture:' } ``` If your project uses [version catalogs](https://docs.gradle.org/current/userguide/version_catalogs.html), you can manage the Capture SDK version in your `libs.versions.toml` file. === "build.gradle" ```kotlin dependencies { implementation libs.bd.capture } ``` === "libs.version.toml" ```toml [versions] bd-capture = "" [libraries] bd-capture = { module = "io.bitdrift:capture", version.ref = "bd-capture" } ``` For the full list of available Android Capture SDK releases visit [Android releases page](releases/android.md). #### Gradle Plugin The gradle plugin provides ergonomic features like [automatic networking instrumentation](./integrations.md#auto-instrumentation-via-gradle-plugin), and [auto-uploading of proguard mapping files](./features/fatal-issues.md#gradle-plugin-android). To enable it at build time you just need to set it up in the `plugins {}` section of your `build.gradle` file: === "Gradle (Kotlin)" ```kotlin plugins { id("io.bitdrift.capture-plugin") version "" } ``` === "Gradle (Groovy)" ```groovy plugins { id 'io.bitdrift.capture-plugin' version '' } ``` Or if you're using `libs.versions.toml`: === "build.gradle" ```kotlin plugins { alias(libs.plugins.bd.capture.plugin) } ``` === "libs.version.toml" ```toml [plugins] bd-capture-plugin = { id = "io.bitdrift.capture-plugin", version.ref = "bd-capture" } ``` The version number used should match the version used in the Capture SDK. Both can be found in the [Android releases page](releases/android.md). !!! note The Capture Gradle Plugin is currently being published to Maven Central only. ### iOS [Swift PM](https://github.com/bitdriftlabs/capture-ios){:target="_blank"} [CocoaPods Version](https://cocoapods.org/pods/BitdriftCapture){:target="_blank"} [GitHub Release](https://github.com/bitdriftlabs/capture-sdk/releases){:target="_blank"} !!! info The iOS SDK requires a minimum iOS version of 15. 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](releases/ios.md). #### Swift Package Manager The Capture SDK can be integrated using Swift Package Manager (SPM) by utilizing the [bitdriftlabs/capture-ios](https://github.com/bitdriftlabs/capture-ios) Swift PM-compatible Git repository. ```swift .package(url: "https://github.com/bitdriftlabs/capture-ios.git", from: "") ``` #### 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 ``` !!! note "" Despite the pod being named `BitdriftCapture`, it is important to note that the Swift module is referred to as `Capture`. ### React Native [npm Version](https://www.npmjs.com/package/@bitdrift/react-native){:target="_blank"} !!! info The React Native SDK requires a minimum iOS version of 15 and Android API level of 23. 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](https://www.npmjs.com/package/@bitdrift/react-native) === "npm" ```bash npm install @bitdrift/react-native ``` !!! note "" 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. ## Configuration Once the dependency has been set up, the logger can be started in the following way: === "Android (Kotlin)" ```kotlin import io.bitdrift.capture.Capture.Logger import io.bitdrift.capture.providers.session.SessionStrategy Logger.start( apiKey = "", sessionStrategy = SessionStrategy.Fixed, ) ``` === "Android (Java)" ```java import io.bitdrift.capture.Capture.Logger; import io.bitdrift.capture.providers.session.SessionStrategy; Logger.start( "", new SessionStrategy.Fixed() ); ``` === "iOS (Swift)" ```swift import Capture Logger.start( withAPIKey: "", sessionStrategy: .fixed() ) ``` !!! info It's recommended that you initialize the SDK as part of your application's [`application(_:willFinishLaunchingWithOptions:)`](https://developer.apple.com/documentation/uikit/uiapplicationdelegate/1623032-application) or [`application(_:didFinishLaunchingWithOptions:)`](https://developer.apple.com/documentation/uikit/uiapplicationdelegate/1622921-application) methods. This allows the SDK to observe system events such as [`didFinishLaunchingNotification`](https://developer.apple.com/documentation/uikit/uiapplication/didfinishlaunchingnotification), which power some of the SDK's out-of-the-box events. === "iOS (Objective-C)" ```objective-c #import [CAPLogger startWithAPIKey:@"" sessionStrategy:[CAPSessionStrategy fixed] ]; ``` !!! info It's recommended that you initialize the SDK as part of your application's [`application(_:willFinishLaunchingWithOptions:)`](https://developer.apple.com/documentation/uikit/uiapplicationdelegate/1623032-application) or [`application(_:didFinishLaunchingWithOptions:)`](https://developer.apple.com/documentation/uikit/uiapplicationdelegate/1622921-application) methods. This allows the SDK to observe system events such as [`didFinishLaunchingNotification`](https://developer.apple.com/documentation/uikit/uiapplication/didfinishlaunchingnotification), which power some of the SDK's out-of-the-box events. === "React Native" ```javascript import { init, SessionStrategy } from '@bitdrift/react-native'; init("", SessionStrategy.Fixed); ``` See the [Configuration](features/configuration.md) 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. !!! note "" See the [SDK Session Management](features/session-management.md) section for information about how to configure a session strategy. !!! tip See the [Issues & Crashes](./features/fatal-issues.md) 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)" ```kotlin // Log line with LogLevel of Info Logger.logInfo(mapOf("key" to "value")) { "Hello world!!" } ``` === "Android (Java)" ```java // Log line with LogLevel of Info Logger.logInfo(Collections.singletonMap("key", "value"), () -> "Info log"); ``` === "iOS (Swift)" ```swift // Log line with LogLevel of Info Logger.logInfo("Hello world!", fields: ["key": "value"]) ``` === "iOS (Objective-C)" ```objective-c // Log line with LogLevel of Info [CAPLogger logInfo:@"Hello world!" fields:@{@"key": @"value"}]; ``` === "React Native" ```javascript import { info } from '@bitdrift/react-native'; // Log line with LogLevel of Info info('Hello world!', { key: 'value' }); ``` !!! note "" The logging calls must be performed on the main process. !!! note "" Read more about other configuration options and usages in our [Configuration](features/configuration.md) 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](releases/android.md). 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. You will still need to [upload the `dSYM` data](features/fatal-issues.md#uploading-debug-information-files) of your final app build in order to ensure that crashes are symbolicated.