Upgrading the SDK

SDK 1.0.0 is the current documented release. This guide defines the process to follow when onboarding provides a newer compatible build.

Before upgrading

Read public release notes and platform-specific migration notes.
Confirm supported OS/runtime baselines and architectures.
Obtain every wrapper and native artifact from the same new release.
Check whether the consent version or public verification key changes.
Prepare rollback artifacts for the currently deployed release.

Never mix release files

Upgrade the package and native binary together:

Android AAR as a whole.
iOS Swift package and its XCFramework.
Node/Electron package pair and prebuilt native binary.
.NET package and runtimes/win-x64/native/p2p_sdk.dll.
Linux header, shared library, pkg-config, and CMake metadata.

Native ABI major 1 indicates symbol-level compatibility, but it does not make arbitrary wrapper/native release combinations supported.

Preserve the existing identity store. Changing identity paths or seeds during an SDK upgrade can invalidate the stored consent scope. A consent-version change may intentionally request a new decision and must be coordinated with product UX.

Regression matrix

Existing accepted installation after upgrade.
Existing declined and revoked states.
Clean install and every consent result.
Connected/disconnected events and online state.
Background mode and OS lifecycle.
Revoke and final shutdown.
Rollback to the previous package without corrupting identity or consent storage.

Native ABI consumers

Check sdk_abi_version() before handle creation. Unknown positive error codes map to a generic SDK failure, and unknown disconnect reason values map to Unknown. Copy the last-error string immediately after a failed call.

Rollout

Use a staged application rollout with SDK version included in sanitized telemetry. Stop rollout if initialization, native loading, consent verification, online rate, or crash metrics regress materially.