Lifecycle

The SDK owns one isolated widget session. The host application owns the signed-in user, screen lifetime, logout, and account replacement.

Controller operations

reload()

Replays the SDK-owned HTML shell in the existing WebView and starts a fresh document lifecycle.

retry()

Clears terminal error state and recreates the isolated widget session.

updateTheme()

Applies light, dark, or system theme to the current widget when possible.

logout()

Clears native authentication and requests in-widget logout without replacing the host session.

isAuthenticated

Reports whether the SDK currently has a usable cached access token. It never returns token text.

sessionSnapshot

Returns redacted lifecycle and authentication state for host UI and diagnostics.

invalidate()

Cancels SDK work and tears down the active session. It does not construct a replacement surface.

One controller attaches to one widget

Create a separate controller for each mounted widget. Do not reuse an attached controller across two views or components.

Readiness and errors

Treat mounted or ready events as the widget-session checkpoint. Authentication failures and widget errors stop the current ready wait. A ready timeout presents error UI without silently replacing the WebView. Use retry only when the host wants a fresh session attempt.

Session expiry

A session-expired event clears the SDK access-token cache. The next authentication request calls embedTokenProvider again. Return a newly minted embed token and do not force a WebView reload.

Soft logout is not host sign-out

logout() is an in-widget operation. It clears native authentication and submits a runtime logout request, but it does not prove server-side revocation and must not delay host cleanup.

The host owns account state

Remove the old widget immediately when the application user signs out or changes account. Do not wait for a widget logout event before clearing host UI and session state.

Replace the surface when the account changes

Changing only the provider function does not reset the authenticated account. A cached token or earlier provider call may still belong to the previous user.

Flutter: Unmount the old widget or change its key using a stable, non-secret host-session key, then supply the new provider.
Android: Dispose and remove the old View. In Compose, replace the keyed subtree so its disposal runs.
iOS: Dispose the UIKit view or replace the SwiftUI representable identity before mounting the new user.
React Native: Unmount the old component or change its React key using a stable, non-secret host-session key.

Multiple widgets

Give each simultaneous widget a distinct storagePrefix, controller, and host identity. Never use an embed token, access token, or raw customer identity as a UI key or storage prefix.

Known isolation boundary

A fresh WebView may share content-origin cookies or storage with other WebViews. Do not clear application-wide WebView storage as a workaround. Verify sensitive account-switch behavior in the real host and runtime.