Installare e configurare l’SDK iOS

Integrate Busymate AI using the official iOS SDK distribution 1.0.1. Source, configuration reference and a buildable demo live in the public repository. Identity uses protocol v2 / bridge build 2.0.0; microphone uses protocol v1 / adapter 1.0.0.

1. Install the pinned version

1. Add https://github.com/serebano/busymate-ai-sdk-ios.git in Xcode Package Dependencies, select exact version 1.0.1, and link the BusymateAI product. Import BusymateAI and WebKit. SDK distribution 1.0.1 requires iOS 15 or later. The older standalone identity source is a separate compatibility artifact.
2. Use the chat URL and assistant slug from your workspace. Preserve the URL's supported parameters and set channel=ios.
3. Read the versioned installation instructions before wiring callbacks.

2. Install before loading chat

Configure account and backend callbacks and install BusymateBridge before the first navigation. The generated starter takes callbacks from your host; implement them using your existing authenticated backend client.

// Swift Package: https://github.com/serebano/busymate-ai-sdk-ios.git (exact 1.0.1)
// Full lifecycle + demo: https://busymate.ai/docs/guides/ios-sdk
import WebKit
import BusymateAI

@MainActor
func installAssistant(
  on webView: WKWebView,
  account: @escaping () -> String?,
  mint: @escaping @MainActor (BusymateBridge.MintRequest) async throws -> BusymateBridge.MintToken?
) {
  BusymateBridge.install(on: webView, config: .init(
    assistant: "your-assistant",
    origins: ["https://your-assistant.busymate.ai"],
    account: account,
    mint: mint
  ))
  // mint calls YOUR authenticated backend with request.nonce; never cache tokens.
  // Backend endpoint: https://YOUR-PRODUCT-DOMAIN/api/bmai/identity
  webView.load(URLRequest(url: URL(string: "https://your-assistant.busymate.ai/?channel=ios")!))
}
// Microphone: declare NSMicrophoneUsageDescription; install and retain
// BusymateMicrophone before load, and forward WKUIDelegate media permission.
// Call BusymateBridge.accountChanged() on login/logout/account changes.

Allow only exact HTTPS origins, without wildcards. The identity bridge adds the assistant's platform origin; the microphone adapter receives its own explicit origin set. Include the actual requesting chat frame origin, not just the outer page's origin.

3. Configure every supported callback

Forward webViewWebContentProcessDidTerminate to BusymateBridge.contentProcessDidTerminate. Keep your navigation policy and media delegate. In SwiftUI, install in makeUIView, retain through the Coordinator and remove the microphone handler during dismantleUIView. Do not install duplicate handlers in updateUIView. The frozen identity bridge has no public uninstall API.

Call BusymateBridge.accountChanged() after login, logout, session/account changes. Foreground resume is observed by the SDK. Your backend must sign the supplied nonce, with ES256, unique jti and expiry within 120 seconds. Never embed signing keys, cache launch tokens or log tokens. See backend signing and the complete configuration reference.

4. Wire the OS microphone callback

Add NSMicrophoneUsageDescription to your app Info.plist with a clear explanation of audio use. Retain BusymateMicrophone and forward WKUIDelegate.requestMediaCapturePermissionFor to allowMedia(origin:type:). It grants only microphone capture after OS authorization for an allowed origin.

A mic or voice tap sends busymate.microphone.v1.request with id and source. The SDK obtains OS permission and returns { id, granted }. Chat waits before capture or voice token minting. Denial and timeout fail closed; cancellation prevents a delayed grant from starting a cancelled session. OS permission remains controlled by the device. After changing permission in Settings, retry explicitly. See microphone lifecycle and troubleshooting.

5. Build and test the demo

Follow the example-app build instructions. Use its Settings screen to change assistant, chat URL, exact origins, backend endpoint, account and microphone/action controls. Guest chat needs no fake identity; authenticated tests use your own backend. The event log supports integration troubleshooting without exposing credentials.

Knowledge, tools, handoff, branding and voice availability are workspace features. Locale and appearance follow supported hosted chat settings. The SDK does not invent native flags for these services or configure your host's audio routing.

Verify

1. Build the demo and verify guest chat.
2. Use your backend to test sign-in, logout and account switching without history leakage.
3. On a physical device test first mic/voice grant, denial, Settings retry and cancellation while the prompt is open.
4. Test external links, close/action controls, background/resume and renderer recovery.