Skip to main content
From v0.28.0 the SDK also ships outside React Native: a Swift package for iOS and the Android bindings with their native libraries. Both are previews. They are built from the same bridge sources the React Native module compiles. From v0.31.0 they leave out the bridge surface only React Native uses, so they carry the generated bindings and the platform transport and storage classes. For a phone app you ship today, use React Native. Use the native packages to evaluate an integration or to build on the generated bindings directly.

Swift package (iOS)

Add the package by URL in Xcode, or in a manifest:
The Swift package is the one install path for a native iOS app: you do not build the Rust library or stitch an XCFramework yourself. Import OfflineProtocolSDK only. Wiring the transport managers to the engine (permissions, background modes, starting each manager) is still the application’s job; the iOS integration guide shows it.

Start an engine on the built-in storage

From v0.34.0 OfflineProtocolReferenceStorage opens the SDK’s own Keychain MLS store and app-container protocol-state store for one (appId, profile) account, the same stores React Native uses, and hands both to initializeMls. Register the event callback before you initialize MLS and start:
Report adoption.warning when it is set: it is the only signal that this account started from a fresh MLS identity because an earlier store on the device belonged to another account or could not be claimed. To erase an account on sign-out, stop the engine, release every reference to it, then call OfflineProtocolReferenceStorage.wipe(appId:profile:); an engine released after the wipe writes its state back into the emptied account.
An app that already has accounts on 0.28.0 to 0.33.0 initialized MLS with its own storage providers, or with initializeMlsWithFileStores. Keep doing so after upgrading. The reference storage uses the SDK’s own per-account namespace, which holds nothing for those accounts, so switching an existing account to it starts a fresh identity with an empty outbox and block list, and adoption.warning does not report it. Use it for new installs, or move existing accounts only with a migration you write and test.

Check a custom storage backend

StorageConformance.run(on:) runs the SDK’s protocol-state conformance suite against a ProtocolStateStorageProvider and returns a report with passed, failures (each with its check and detail) and isGreen. Green is the definition of a supported backend. Run it on a scratch instance, off the main thread, since the suite writes several megabytes:

Lab-only cleartext

OfflineProtocolDevelopmentCleartextConfig.make(appId:profile:) builds a lab configuration with Bluetooth LE on, every other transport off, and encryption and requireEncryption off. Never ship a build that uses it. OfflineProtocolEncryptFailedDiagnostics logs a one-time remedy when a send fails with EncryptFailed because MLS was not initialized.

Upgrade the package

Bump the package to the SDK release you are adopting (File → Packages → Update to Latest Package Versions in Xcode, or the version in Package.swift) and clean-build; nothing is rebuilt locally. The package is 0.x, so a minor release can change the API and from: accepts any later 0.x: read the upgrade guide for every release in between first. Offline-Protocol/offline-protocol-swift is generated by the SDK’s release workflow and tagged X.Y.Z to match the SDK release; changes made there are overwritten, so file issues in the SDK repository. The same release also attaches the XCFramework (offline-protocol-0.34.0-swiftpm-xcframework.zip, offline-protocol-0.34.0-ios-xcframework.zip) and the assembled package (offline-protocol-0.34.0-swift-package.tar.gz). To vendor the tarball instead of the repository, verify both assets with gh attestation verify <asset> --repo Offline-Protocol/offline-protocol-sdk, and check that the checksum: in the tarball’s Package.swift matches swift package compute-checksum of the zip from the same release. See the native iOS distribution guide. The iOS peer-stream manager uses Network framework, so the interoperability break with 0.27 applies here as well. Declare the Info.plist keys in iOS peer streams before enabling that transport. From v0.29.0 the iOS Bluetooth LE central writes its hello once per connection, so an iPhone can start a session with a Python host it connects to over Bluetooth LE. From v0.31.0 the iOS peripheral serves the Hello characteristic too, so a central that writes its identity, such as a browser over Web Bluetooth, is bound to its address at once.

Android bindings

From v0.29.0 the Android library is on Maven Central as com.offlineprotocol:offline-protocol-sdk. Add it to the app module:
The library’s floor is Android 7 (API 24), compiled against API 34. The AAR contains: It depends on JNA 5.19.1 as an Android archive, and Gradle adds that for you. The React Native module that ties the transports to the engine is not part of it, so wiring them is the application’s job. Artifacts are signed with the Offline Protocol release key, fingerprint 55FD B6AB C147 BD60 9EE0 447D C671 8335 845D 9497. The same bindings and native libraries are also attached to the v0.34.0 GitHub release as offline-protocol-0.34.0-android.zip, for builds that cannot use Maven Central. The library is built from bindings/kotlin in the SDK repository; see its README. The Android integration guide shows the bindings in Kotlin.

Imports and native library names

Drive the engine through uniffi.offline_protocol (OfflineProtocol, ProtocolConfig, EventCallback), and import the hand-written bridge types the library ships from com.offlineprotocol by name (OfflineProtocolReferenceStorage, StorageConformance, InternetManager), never with a wildcard: that package also holds the React Native module, which the library leaves out. The AAR already carries the native library under the right name. An app that builds the Rust library itself and copies the .so files into its own jniLibs must rename them: cargo writes liboffline_protocol_uniffi.so, and the generated Kotlin loads libuniffi_offline_protocol.so. A copy that keeps the cargo name builds and fails at the first engine call with UnsatisfiedLinkError. From v0.34.0 the library exposes both names as OfflineProtocolJniLibrary.LOADED_BASENAME and OfflineProtocolJniLibrary.CARGO_OUTPUT_BASENAME, and scripts/check_manual_android_jni_libs.py in the SDK repository checks a jniLibs tree. See Android JNI names and imports.

Built-in storage and conformance

From v0.34.0 the Android library has the same helpers as the Swift package. OfflineProtocolReferenceStorage.initializeMls opens the Keystore-backed MLS store and the app-container protocol-state store for one account, the stores React Native uses, and returns what happened to an earlier store on the device:
Report adoption.warning when it is set: it means this account starts from a fresh MLS identity. On sign-out, stop the engine, close() it, then call OfflineProtocolReferenceStorage.wipe(context, appId, profile). Run StorageConformance.run off the main thread on a scratch backend; a green report is what makes a custom protocol-state backend supported. As on iOS, an app whose existing accounts use its own storage providers keeps them after upgrading. OfflineProtocolDevelopmentCleartextConfig.make(appId, profile) builds the lab-only cleartext configuration; never ship a build that uses it. The SDK repository’s consumer checks compile these calls against the published library, and the Swift consumer check against the package.

Bluetooth LE signal strength

From v0.31.0 the engine reports live signal strength for linked Bluetooth LE peers, off by default. Call set_peer_rssi_events(true) (setPeerRssiEvents in Swift and Kotlin) and the engine emits peer_rssi events with the peer’s off1… address, the transport and the reading in dBm, at most four a second per peer. While readings flow, each link’s quality follows the smoothed readings and the mesh relay ranks neighbours by it. A reading is attributed only to a peer that proved its address on a link, and signal strength proves nothing about who sent it, so do not treat it as evidence of who is nearby (threat model R29). The React Native module turns readings on while a peer_rssi listener exists; see events.

Desktop native libraries

The same release attaches the native library for linux-x86_64, linux-aarch64, macos-arm64 and windows-x86_64. Python users get these inside the PyPI wheels; Rust users build from the crates. From v0.30.0 each desktop archive also carries the C header for the C binding, and the Windows archive the DLL’s import library. The Java and Ruby bindings load the same library. From v0.30.0 link-time optimisation reaches every shipped library, and the iOS and Android libraries are also built for size. Measured on the macOS arm64 build, link-time optimisation cut the static library behind the iOS framework from 138 MB to 23 MB and the shared library from 11.5 MB to 10.9 MB; building for size took that shared library on to 8.5 MB. Building for size makes CPU-bound work in the SDK slower; see upgrade from v0.29.