Mobile Widget SDKs

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