# iOS SDK: the AI waiter in your Swift app

> Add Tamr's AI waiter to an iOS app in Swift with TamrWaiter: Swift Package Manager, UIKit and SwiftUI, signed-in diners, cart lines, voice notes and debug mode.

Source: https://tamr.link/docs/sdks/ios

`TamrWaiter` shows the waiter in an iOS app, in a `WKWebView` that stays on Tamr's origin, for UIKit and SwiftUI. It has no dependencies.

## Requirements

iOS 16 or later, Xcode 16 or later (Swift 6).

## Install

In Xcode: **File > Add Package Dependencies**, paste `https://github.com/abiroot/tamr-waiter-ios`, set the rule to **Up to Next Major Version** from `1.0.0`, and add `TamrWaiter` to your app's target. Or in `Package.swift`:

```swift
.package(url: "https://github.com/abiroot/tamr-waiter-ios", from: "1.2.0"),
// and in your target's dependencies:
.product(name: "TamrWaiter", package: "tamr-waiter-ios"),
```

List your app's bundle id on the app key. The SDK sends it; a key used from an app it doesn't list is logged, never refused.

## Open the waiter

Create one controller where the waiter is likely to be opened, preload it, and show it on a tap:

```swift
import TamrWaiter

let waiter = try TamrWaiterController(
    appKey: "tamr_pk_test_…",
    restaurant: "your-restaurant",
    locale: "ar"          // optional: branch, appearance, table, tableScan, mode, launch, debug, onLog
)
waiter.preload()

// Who the diner is, asked whenever the page needs a fresh token. Return nil for "no one".
waiter.setIdentityProvider { _ in
    guard let token = try await myBackend.tamrToken() else { return nil }   // your backend signs it
    return .token(token)
}

// Orders go to your own cart ("Orders go to: the app's cart"): answer each line.
waiter.onCartAdd { change in
    Reply(ok: true, lines: change.lines.map { LineAnswer(lineId: $0.lineId, ok: true) })
}

// Everything the page tells you.
waiter.on("payment.completed") { message in
    if let paid = message as? PaymentCompletedMessage { print("paid", paid.data.paymentId) }
}

// On a tap, UIKit:
present(TamrWaiterViewController(controller: waiter), animated: true)
// or SwiftUI:
.sheet(isPresented: $open) { TamrWaiterView(controller: waiter) }
```

- `TamrWaiterViewController` (UIKit): a page sheet, a full page, or a screen of a navigation stack, with loading and retry states.
- `TamrWaiterView` (SwiftUI): the same, for `.sheet` and `.fullScreenCover`.
- For a full page, pass `presentation: .fullScreen` and create the controller with `appearance: Appearance(showBack: .set(true))` so the page's back arrow closes it.

Call `dispose()` when the diner signs out, and create a new controller for the next diner.

## Who the diner is

`setIdentityProvider(_:)` returns `.token(…)`, `.code(…)` or `nil`, within 15 seconds. See [Diner identity](https://tamr.link/docs/guides/diner-identity).

## Voice notes

Optional: without them the waiter works by text. Add the microphone's purpose to your app's `Info.plist`:

Info.plist:

```xml
<key>NSMicrophoneUsageDescription</key>
<string>Talk to the waiter with your voice.</string>
```

Then answer `onMicrophonePermission` with the system's permission:

```swift
waiter.onMicrophonePermission = { await AVAudioApplication.requestRecordPermission() }   // iOS 17+
```

The SDK never asks for the camera: a camera request is refused without asking your app, and WebKit's own prompt never shows.

## Payments

With Tamr Pay on, the provider's page opens in `SFSafariViewController` over the chat, never inside the web view, and only when the link is `https`. When the diner closes it, the waiter checks the payment.

## Debug mode

`debug: true` prints every message both ways and the page's trace to `onLog` or the system log (subsystem `link.tamr.waiter`), and makes the web view inspectable in Safari's Web Inspector in a debug build of your app. See [Debug mode](https://tamr.link/docs/guides/debugging).

## Methods

The page's messages are protocols and the SDK's own kinds are structs, not enums, so a new case never breaks your `switch`: keep a `default` branch.

| Method | What it does | Since |
| --- | --- | --- |
| `preload()` | Load the chat hidden, so it opens at once | 1.0.0 |
| `reload()`, `dispose()` | Load again after a failure; stop for good | 1.0.0 |
| `setIdentityProvider(_:)` | Who the diner is: .token(…), .code(…) or nil | 1.0.0 |
| `onCartAdd`, `onCartUpdate`, `onCartRemove` | Answer the waiter's cart proposals, per line | 1.0.0 |
| `on(_:_:)` | Everything the page tells your app | 1.0.0 |
| `setLocale`, `setAppearance`, `setText`, `setTheme`, `setContext`, `setStarters`, `setRestrictions` | Kept and sent again whenever the page loads again | 1.0.0 |
| `setGoal(_:)` | The diner's nutrition goal as your app keeps it | 1.1.0 |
| `sendCart(_:)`, `sendMessage(_:)`, `newChat()`, `clearIdentity()` | One-off messages, held until the chat is ready | 1.0.0 |
| `requestReview(orderId:dishes:)` | After an order your backend sent: ask the diner to rate each dish | 1.1.0 |
