Skip to main content
These guides target v0.28.0. Pin the package while qualifying your application and review the versioned upgrade guide before changing it.

​
Upgrade procedure

  1. Record the currently deployed package and native-library versions.
  2. Preserve a supported backup of identity and application state.
  3. Build against the target release and resolve changed APIs.
  4. Test restart, pending work and mixed-version peer behaviour on representative devices.
  5. Release to a limited cohort and inspect failures before expanding.
A previous binary is not automatically a safe rollback for newer persisted state. Follow the release’s storage compatibility guidance. Source on main can contain unreleased features; do not combine generated bindings from one revision with a native library from another.

​
Runtime changes to qualify

In v0.26, delivery state survives restart, the pending TTL changes from 30 minutes to 24 hours, and deduplication defaults become 2,000 entries retained for 24 hours. Account for the larger retention window in disk and retry budgets. In v0.27, relay group traffic reaches phones. Test group delivery over the relay after upgrading; compilation alone does not exercise these paths.

​
Upgrade from v0.27

Two changes can stop a build and one changes behaviour at run time. The SDK’s UPGRADING §26 lists every change that compiles unchanged and behaves differently. Also check these run-time changes:
  • wifiDirect: { enabled: true } now starts the transport from start() on both platforms. Before, the setting did nothing without enableTransport('wifiDirect'). On iOS the first start shows the Local Network prompt. Remove the setting if you did not mean to run the transport.
  • On Android 10 and later, wifiDirect.autoAccept: true now forms the Wi-Fi Direct group without a system dialog. An app that already set it starts forming groups on upgrade; set it to false to keep the old behaviour. groupOwnerIntent is deprecated and unused.
  • The Android module declares the Wi-Fi Direct permissions. Request NEARBY_WIFI_DEVICES at run time on Android 13 and later, and ACCESS_FINE_LOCATION on 12 and lower.
  • neighbor_lost fires once, when the last Bluetooth LE or Wi-Fi Direct link to a peer ends. On Android it fires 15 seconds after the last link closes.
  • transport_switched to Wi-Fi Direct fires when the first link proves a peer, not when the transport starts.
  • React Native emits a diagnostic event with message: "native_event_gap" when an event from the native module never reached JavaScript.
  • DiagnosticEvent.level now declares debug. Android emits warning where four GATT server diagnostics used to say warn.
  • Deduplication defaults grow to 5,000 entries retained for 7 days. A config that sets the old values keeps them.
  • DataStore.setInterest called before start() is held and applied during start(). A refused pattern now rejects start(). Declare interests before start() on every launch.
  • Documents are stored and sent only when flush() or flushAll() runs. Flush on a short throttle while the user edits, and once more when editing stops.

​
What v0.28.0 adds

The v0.28.0 changelog has every change with its reasoning.

​
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.