Mobile Widget SDKs

# Troubleshooting

Start with the visible symptom, then verify the host prerequisite and per-widget configuration before changing SDK lifecycle code.

> Record the failing layer
>
> Token minting, native serverless authentication, WebView loading, widget readiness, callbacks, and host navigation are separate checkpoints. A successful backend token response does not prove the widget mounted.

## Authentication returns 403, then the WebView shows 502

**Likely cause**

The configured clientOrigin is not allowlisted on this exact widget.

**What to do**

Allow the HTTPS origin on the target widget. Do not rely on another widget in the same environment working.

## One widget works while another widget fails

**Likely cause**

Origin access and supplied widget configuration are evaluated per widget.

**What to do**

Check the failing widget ID, matching bundle URL, environment, and allowlisted origin independently.

## External links do nothing

**Likely cause**

The host did not provide onExternalNavigation or did not open the delegated HTTPS URL.

**What to do**

Handle the callback and open the URL through the system browser or an approved in-app browser.

## Authentication loops after the app has been idle

**Likely cause**

The application returns a cached or expired embed token when the SDK authenticates again.

**What to do**

Mint a fresh embed token from the backend on every provider call after session expiry.

## Two widgets conflict or the second widget stays blank

**Likely cause**

The two instances share storagePrefix, controller state, or host component identity.

**What to do**

Give each widget a distinct non-secret storage prefix, controller, and host key.

## Android widget stays blank with no network activity

**Likely cause**

The host application does not declare the INTERNET permission.

**What to do**

Add android.permission.INTERNET to the host manifest. The library AAR does not add it.

## Android reports an unsupported platform or bridge

**Likely cause**

The device System WebView does not support WEB_MESSAGE_LISTENER.

**What to do**

Update Android System WebView or the OEM WebView. The SDK intentionally has no insecure bridge fallback.

## React Native authentication fails while creating a nonce

**Likely cause**

crypto.getRandomValues is unavailable before the widget mounts.

**What to do**

Load the documented Web Crypto polyfill before the first ReturningAIWidget component.

## The widget behaves differently in Expo Go

**Likely cause**

Expo Go is not a supported host for this SDK.

**What to do**

Use an Expo SDK 57 development build created with expo run:ios or expo run:android.

## Xcode cannot resolve the iOS package

**Likely cause**

The current Swift package repository is private or the GitHub account does not have access.

**What to do**

Authenticate Xcode or SwiftPM with a GitHub account or token that can read ReturningAI/returningai-widget-swift-sdk.

## Safe diagnostics

- Log stable error codes and sanitized messages.
- Record HTTP status, widget ID label, platform, and lifecycle phase.
- Confirm the package version and runtime URL used by the host.
- Never log access credentials, embed tokens, access tokens, complete authentication bodies, or callback signatures.