---
title: "Install and configure the iOS SDK"
description: "Install the versioned iOS SDK, configure identity and microphone permission, and build the example app."
last_updated: "2026-10-07T13:08:47+03:00"
---
# Install and configure the iOS SDK

Source: https://busymate.ai/ko/docs/guides/ios-sdk
Last modified: 2026-10-07T13:08:47+03:00
Integrate Busymate AI using the official iOS SDK distribution **1.0.1**. Source, configuration reference and a buildable demo live in the [public repository](https://github.com/serebano/busymate-ai-sdk-ios/tree/1.0.1). 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](https://github.com/serebano/busymate-ai-sdk-ios/blob/1.0.1/README.md) 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
// 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

| Setting | Purpose |
| --- | --- |
| `assistant` | Required assistant slug. |
| `origins` | Extra exact HTTPS chat origins. |
| `account` | Current account ID or nil/null when signed out. |
| `mint` | Required backend callback returning a fresh token and matching nonce. |
| `onAction` | Optional app action handler; return true only when handled. |
| `onClose` | Optional host dismissal callback; leave absent when disabled. |
| `authCallbackScheme` | Optional return scheme for `ASWebAuthenticationSession`; register it in your app URL types. |

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](https://busymate.ai/ko/docs/guides/identity-backend-signing) and the [complete configuration reference](https://github.com/serebano/busymate-ai-sdk-ios/blob/1.0.1/docs/configuration.md).

## 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](https://github.com/serebano/busymate-ai-sdk-ios/blob/1.0.1/docs/microphone.md).

## 5. Build and test the demo

Follow the [example-app build instructions](https://github.com/serebano/busymate-ai-sdk-ios/blob/1.0.1/example-app/README.md). 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.

<!-- qa:start -->
### Where is the full API reference?
The versioned repository's configuration, identity and microphone guides describe all public SDK settings and lifecycle callbacks.

### Does the demo authenticate without my backend?
No. Guest mode works when enabled; authenticated mode requires your real backend and current session.

### Which updates require an app release?
SDK changes, OS permissions and native capabilities require an app release. Hosted chat changes arrive from the service.
<!-- qa:end -->