Installation

Requirements

Requirement	Minimum
React Native	0.70.0
React	16.8.0
iOS deployment target	13.0
Android `minSdkVersion`	24
Android `compileSdk` / `targetSdk`	34
JDK (for the Android build)	17
Swift	5.5
Node.js	18+

The SDK is a native module, so it does not run in Expo Go. A custom dev client or a bare React Native project is required.

Install the Package

npm install @offline-protocol/mesh-sdk

Then, for iOS:

cd ios && pod install

That is the whole installation. Autolinking handles both platforms, so you do not need a pod entry, a post_install hook, a settings.gradle include, or a MainApplication registration. Pre-built native libraries ship in the package for both platforms. pod install should list MeshSdk under “Auto-linking React Native modules”. The iOS native binary ships as an XCFramework, so CocoaPods picks the right slice per build SDK and device and simulator builds both work with no linker configuration.

Upgrading from a version below 0.20.0? Delete these from your ios/Podfile. They now break the build:

Any pod 'MeshSdk', ... line, with or without :modular_headers => true. A surviving line pointing into .../mesh-sdk/ios fails pod install outright with a “no podspec found” error.
Any post_install hook that configured MeshSdk, in particular one setting DEFINES_MODULE, SWIFT_INCLUDE_PATHS, LIBRARY_SEARCH_PATHS, or OTHER_LDFLAGS.
Any flag naming offline_protocol_uniffi_sim or offline_protocol_uniffi_device. Those archives no longer exist and linking them fails with library not found.

Simulator builds work from 0.20.0 onward. If you previously concluded this SDK was device-only, that was a packaging bug, and any workaround you carried must be removed.

iOS Setup

Info.plist

<key>NSBluetoothAlwaysUsageDescription</key>
<string>This app uses Bluetooth to communicate with nearby devices</string>

<key>NSBluetoothPeripheralUsageDescription</key>
<string>This app uses Bluetooth to communicate with nearby devices</string>

<!-- Required for reliable BLE operation. Without these, iOS throttles or stops
     BLE scanning and advertising, and CoreBluetooth state restoration will not work. -->
<key>UIBackgroundModes</key>
<array>
    <string>bluetooth-central</string>
    <string>bluetooth-peripheral</string>
</array>

Both background modes are effectively mandatory: the SDK creates its central manager with a state-restoration identifier, which CoreBluetooth only honors when bluetooth-central is declared.

Additional keys for Wi-Fi Direct

The iOS Wi-Fi Direct path uses MultipeerConnectivity. iOS 14+ refuses local-network discovery without these:

<key>NSLocalNetworkUsageDescription</key>
<string>This app uses the local network to discover and communicate with nearby devices</string>

<key>NSBonjourServices</key>
<array>
    <string>_offline-proto._tcp</string>
    <string>_offline-proto._udp</string>
</array>

The Bonjour service names must match the SDK’s MultipeerConnectivity service type, which is offline-proto. MultipeerConnectivity registers both the TCP and UDP variants, so declare both.

No entitlements or capabilities are required. The pod links Foundation, CoreBluetooth, and MultipeerConnectivity.

Android Setup

What the SDK already declares

The SDK ships its own AndroidManifest.xml, and these entries merge into your app automatically, so you do not need to copy them:

<!-- BLE: Android 11 and below -->
<uses-permission android:name="android.permission.BLUETOOTH" android:maxSdkVersion="30" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" android:maxSdkVersion="30" />

<!-- BLE: Android 12+ -->
<uses-permission android:name="android.permission.BLUETOOTH_SCAN"
    android:usesPermissionFlags="neverForLocation" />
<uses-permission android:name="android.permission.BLUETOOTH_ADVERTISE" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />

<!-- Background mesh operation -->
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_CONNECTED_DEVICE" />
<uses-permission android:name="android.permission.WAKE_LOCK" />

<uses-feature android:name="android.hardware.bluetooth_le" android:required="false" />

The neverForLocation flag on BLUETOOTH_SCAN and the maxSdkVersion="30" gating propagate into your merged manifest. neverForLocation has Play Console data-safety implications you inherit, so it is worth knowing it is there.

What your app must declare

The SDK deliberately does not force these on consumers, but the code requires them:

<!-- Internet, Nostr, and relay transports -->
<uses-permission android:name="android.permission.INTERNET" />

<!-- Required for BLE scanning on Android 11 and below, and for Wi-Fi Direct on every level -->
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

<!-- Only if you enable Wi-Fi Direct -->
<uses-permission android:name="android.permission.NEARBY_WIFI_DEVICES" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.CHANGE_WIFI_STATE" />

<!-- Android 13+: without this the mesh keep-alive notification is silently suppressed -->
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />

POST_NOTIFICATIONS is easy to miss. start() unconditionally launches a foreground service that posts a “Mesh Active” notification with a Stop action. On Android 13+ that notification is silently suppressed without the runtime grant, so users get no way to see or stop the mesh.

ProGuard / R8

Nothing to configure. The SDK ships consumerProguardFiles, so its keep rules are applied to your release build automatically. Without them, release builds would silently lose the BLE mesh transport while debug builds kept working, but the rules are already handled for you.

Runtime Permissions

Android

The SDK checks permissions but never requests them. Your app must request them before calling start(), or the SDK emits a diagnostic event at error level with “Missing Bluetooth permissions”.

import { PermissionsAndroid, Platform } from 'react-native';

async function requestMeshPermissions(): Promise<boolean> {
  if (Platform.OS !== 'android') return true;

  const permissions: string[] = [];
  const apiLevel = Platform.Version as number;

  if (apiLevel >= 31) {
    permissions.push(
      PermissionsAndroid.PERMISSIONS.BLUETOOTH_SCAN,
      PermissionsAndroid.PERMISSIONS.BLUETOOTH_CONNECT,
      PermissionsAndroid.PERMISSIONS.BLUETOOTH_ADVERTISE,
      PermissionsAndroid.PERMISSIONS.ACCESS_FINE_LOCATION,
    );
  } else {
    permissions.push(
      PermissionsAndroid.PERMISSIONS.ACCESS_FINE_LOCATION,
      PermissionsAndroid.PERMISSIONS.ACCESS_COARSE_LOCATION,
    );
  }

  if (apiLevel >= 33) {
    permissions.push(PermissionsAndroid.PERMISSIONS.POST_NOTIFICATIONS);
    // Only if you enable Wi-Fi Direct:
    // permissions.push(PermissionsAndroid.PERMISSIONS.NEARBY_WIFI_DEVICES);
  }

  const results = await PermissionsAndroid.requestMultiple(permissions);
  return Object.values(results).every(
    (r) => r === PermissionsAndroid.RESULTS.GRANTED,
  );
}

BLUETOOTH and BLUETOOTH_ADMIN are install-time permissions on API 30 and below, so they do not need a runtime request. You can also check and prompt for Bluetooth itself:

if (!(await protocol.isBluetoothEnabled())) {
  await protocol.requestEnableBluetooth();  // Android only; returns false on iOS
}

iOS

No runtime API call is needed. The system prompts on first CoreBluetooth use, driven by the Info.plist usage descriptions.

Optional: Android Mesh Wake

This is the only manual native edit the SDK requires, and only if you want the mesh to recover after Android kills your process. Add to your app’s AndroidManifest.xml, inside <application>:

<meta-data android:name="com.offlineprotocol.MESH_WAKE_ENABLED" android:value="true" />
<!-- Optional; default 60, clamped to 10-300 -->
<meta-data android:name="com.offlineprotocol.MESH_WAKE_TIMEOUT_SECONDS" android:value="60" />

Then register the task at module scope in index.js, not inside a component:

import { AppRegistry } from 'react-native';
import { registerMeshWakeTask } from '@offline-protocol/mesh-sdk';
import App from './App';

AppRegistry.registerComponent('MyApp', () => App);

registerMeshWakeTask(async ({ reason }) => {
  // Persist inbound messages before start(), be idempotent, and resolve promptly.
  await protocol.start();
});

Both halves are required; the manifest flag alone does nothing. See registerMeshWakeTask for the four caller obligations.

Mesh wake requires React Native 0.76.5+ when the New Architecture is enabled. Headless tasks did not work under bridgeless before 0.76 and were patchy until 0.76.5. On RN 0.84 and 0.85 a core bug (fixed in 0.86) can leave the wake service running after the task finishes.

Troubleshooting

Linking error

If you see the “doesn’t seem to be linked” error:

Run pod install (iOS) and rebuild natively. A JS-only reload will not pick up native changes.
Confirm pod install output lists MeshSdk under “Auto-linking React Native modules”.
Run npx react-native config and check platforms.ios.podspecPath ends in MeshSdk.podspec.
Remove any leftover manual pod 'MeshSdk' line; it can shadow the autolinked pod.
Verify you are not using Expo Go.

Simulator link failures

Undefined symbols, or “building for iOS Simulator, but linking in object file built for iOS”, means a leftover manual post_install hook is still linking archives by hand. Remove it per the upgrade warning above.

Upgrading to 0.21.0

A native rebuild is required, because new source files are compiled in on both platforms. Run pod install for iOS. A JS-only update will not pick them up.

Downgrading is not a rollback. The first launch on 0.21.0 moves delivery state out of the credential store into the app container and deletes the old copy. An older build comes up with an empty outbox, an empty pending queue, and an empty block list, meaning every previously blocked peer is silently unblocked. Roll forward with a hotfix rather than reverting the binary.

Next Steps

Set up the SDK in your app

Getting started

Technical Specification

ID SDK

Mesh SDK

Examples & Tutorials

Proof of Location

Glossary

Support

Legal

Installation - React Native

Installation

Requirements

Install the Package

iOS Setup

Info.plist

Additional keys for Wi-Fi Direct

Android Setup

What the SDK already declares

What your app must declare

ProGuard / R8

Runtime Permissions

Android

iOS

Optional: Android Mesh Wake

Troubleshooting

Linking error

Simulator link failures

Upgrading to 0.21.0

Next Steps

​Installation

​Requirements

​Install the Package

​iOS Setup

​Info.plist

​Additional keys for Wi-Fi Direct

​Android Setup

​What the SDK already declares

​What your app must declare

​ProGuard / R8

​Runtime Permissions

​Android

​iOS

​Optional: Android Mesh Wake

​Troubleshooting

​Linking error

​Simulator link failures

​Upgrading to 0.21.0

Next Steps

Installation

Requirements

Install the Package

iOS Setup

Info.plist

Additional keys for Wi-Fi Direct

Android Setup

What the SDK already declares

What your app must declare

ProGuard / R8

Runtime Permissions

Android

iOS

Optional: Android Mesh Wake

Troubleshooting

Linking error

Simulator link failures

Upgrading to 0.21.0