Install and configure the macOS SDK

Integrate Busymate AI in a native Mac app using the official macOS SDK distribution 1.0.1: a Swift package for WKWebView on AppKit, with a SwiftUI wrapper. Source, the configuration reference and a buildable demo live in the public repository, released as 1.0.1. Identity uses protocol v2 / bridge build 2.0.0; microphone uses protocol v1 / adapter 1.0.0. The release manifest pins the source hashes. Its CONTRACT-v2.md hash matches https://busymate.ai/sdk/v2/2.0.0/SHA256SUMS.

1. Install the pinned version

1. In Xcode, choose File › Add Package Dependencies, enter https://github.com/serebano/busymate-ai-sdk-macos.git, select exact version 1.0.1 and link the BusymateAI product. In a package manifest, use .package(url: "https://github.com/serebano/busymate-ai-sdk-macos.git", exact: "1.0.1").
2. The SDK requires macOS 12 or later and Swift tools 5.9 or later (Swift 5 language mode).
3. Use the SDK's chat controller. It installs the identity bridge and BusymateMicrophone before the first load, pins top-level navigation to the allowed origins, sends other links to the default browser and recovers from web content process termination. Present it with the SDK's AppKit view controller or SwiftUI view. Keep the controller in an ObservableObject, not in the view.

Read the versioned installation instructions before wiring callbacks.

2. Load the chat as the window's page

Use the chat URL and assistant slug from your workspace, for example https://YOUR_ASSISTANT.busymate.ai/?channel=desktop_sdk&locale=en. Keep the URL's supported parameters and set channel=desktop_sdk. The chat is the window's top-level page: it uses the normal chat layout and shows your locale from the first frame. Do not use channel=embed, which needs an allowed parent web page and refuses to start as a window, or channel=desktop, which is reserved for the Busymate AI desktop app.

Allow only exact HTTPS origins, without wildcards. The assistant slug adds exactly https://<assistant>.busymate.ai. Add https://busymate.ai when you load a /support/<assistant> URL, and add your mapped support host if you have one.

3. Configure every supported callback

The chat controller takes chatURL, a bridge configuration, microphone (default on) and an optional WKWebViewConfiguration. The bridge configuration takes:

Your backend must sign the supplied nonce with ES256, a unique jti and an expiry within 120 seconds. Never ship signing keys, cache launch tokens or log tokens. See backend signing and the complete configuration reference.

4. Wire the OS microphone callback

Call the bridge's accountChanged() after login, logout and account switches.

Add NSMicrophoneUsageDescription to your app's Info.plist and localize it. With the App Sandbox, add com.apple.security.network.client and com.apple.security.device.audio-input. With the hardened runtime outside the sandbox, add the Audio Input capability. macOS asks for microphone permission when the customer first taps. Only an OS grant plus an allowed-origin WebKit media decision permits recording.

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 for that reply before capture or voice token minting. Denial and timeout fail closed, and cancellation prevents a delayed grant from starting a cancelled session. Opening the chat never asks. See microphone lifecycle and troubleshooting.

5. Build and test the demo

Open the Xcode project in example-app/, select its example scheme and My Mac, and run. Its settings pane changes the chat URL, locale, origins, guest or identified mint, microphone and callbacks. Follow the example-app build instructions. Guest chat needs no fake identity, and authenticated tests use your own backend. The event log helps with integration troubleshooting without exposing credentials.

Knowledge, tools, handoff, branding and voice availability are workspace features. Locale and appearance follow the supported hosted chat parameters. The SDK does not invent native flags for these services.

Verify

1. Build the example app and verify guest chat, loaded with channel=desktop_sdk.
2. Load ?channel=desktop_sdk&locale=de: the first frame is in German and the chat fills the window with no extra title-bar inset.
3. Use your backend to test sign-in, logout and account switching without history leakage.
4. On a real machine, test the first mic/voice grant, denial, retry after changing the OS setting, and cancellation while the prompt is open.
5. Test external links, close/action callbacks, window re-activation and renderer recovery.