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.