Mobile Widget SDKs

iOS

Use the binary Swift package to host Returning.AI custom widgets in SwiftUI or UIKit applications.

Package repository: ReturningAI/returningai-widget-swift-sdk

Requirements

• iOS 15 or later and Swift tools 6.0.
• An HTTPS client origin allowlisted for the target widget.
• A trusted backend that returns freshly minted embed tokens.
• Repository access for the current private Swift package.

Add the Swift package

In Xcode, choose File → Add Package Dependencies and enter the repository URL above. Select exact version 0.1.1. A host package can declare the same dependency directly.

.package(
    url: "https://github.com/ReturningAI/returningai-widget-swift-sdk.git",
    exact: "0.1.1"
)

Add ReturningAIWidget for UIKit. Add both ReturningAIWidget and ReturningAIWidgetSwiftUI for SwiftUI.

SwiftUI

Keep the controller with the host screen and fetch embed tokens through the application backend.

import ReturningAIWidget
import ReturningAIWidgetSwiftUI

let controller = ReturningAIWidgetController()
let configuration = ReturningAIWidgetConfiguration.customBundle(
    widgetId: "YOUR_SUPPLIED_WIDGET_ID",
    bundleURL: URL(string: "YOUR_SUPPLIED_BUNDLE_URL")!,
    clientOrigin: URL(string: "https://mobile-client.example")!,
    runtimeURL: URL(
        string: "https://unpkg.com/@returningai/widget-sdk/dist/rai-widget.iife.js"
    )!
)

ReturningAIWidgetSwiftUI.ReturningAIWidget(
    configuration: configuration,
    embedTokenProvider: {
        try await backend.fetchReturningAIEmbedToken()
    },
    controller: controller,
    onExternalNavigation: { url in
        appRouter.openExternal(url)
    }
)

UIKit

The UIKit product exposes ReturningAIWidgetView. Normal deallocation cleans up the session; call dispose() when ending it manually.

let widgetView = ReturningAIWidgetView(
    configuration: configuration,
    embedTokenProvider: {
        try await backend.fetchReturningAIEmbedToken()
    }
)

containerView.addSubview(widgetView)

// When manually ending this widget surface:
widgetView.dispose()

Session lifecycle

• Use ReturningAIWidgetController for reload, retry, theme, soft logout, session queries, and terminal invalidation.
• On host logout or account change, dispose the old UIKit view or replace the SwiftUI representable identity.
• A new user requires a new widget surface and a new embed-token provider.

Return to the Mobile Widget SDK overview.