Construction
Section titled “Construction”Use the supported platform wrapper. Protected UI wrappers return an instance only after an accepted consent result. Create one instance per logical peer and assign a single owner such as an application-level service or controller.
Connect is asynchronous state
Section titled “Connect is asynchronous state”connect() returning success means the connection supervisor started or was already active. Discovery, authentication, and transport setup may still be in progress.
Use one of these online signals:
- Connected callback.
- Wrapper
connectedevent. - Kotlin lifecycle state or event stream.
isOnline/is_onlineafter an event or deliberate poll.
Do not grant rewards, show an active status, or infer usable connectivity from the return value of connect() alone.
Disconnect and reconnect
Section titled “Disconnect and reconnect”The SDK can report Manual, Network, ServerUnavailable, TokenExpired, LowBattery, DiscoveryError, ProtocolError, or Unknown. Policy-driven or network failures may reconnect internally. Application code should update state and telemetry but should not run its own tight reconnect loop.
Pause versus final release
Section titled “Pause versus final release”- Call disconnect when the logical peer should pause but the object may be reused.
- Call
close(),free(), orDispose()exactly once at final shutdown. - Do not use the instance after final release or successful revoke.
- Direct native consumers must serialize calls and clear callbacks before freeing managed callback state.
Callback safety
Section titled “Callback safety”Android and iOS wrappers marshal callbacks onto configured application queues. Node emits events on the JavaScript event loop. C callbacks can run on SDK runtime threads. Keep every handler short and move blocking work to an application-owned worker.
Terminal state
Section titled “Terminal state”After close/free/dispose, the instance is terminal. Reconnecting requires a new SDK instance created through the current consent state.