# Flutter SDK: the AI waiter in your Flutter app

> Add Tamr's AI waiter to a Flutter app on iOS and Android with tamr_waiter: install, open the waiter as a sheet, page or widget, sign diners in and take cart lines.

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

`tamr_waiter` shows the waiter in a Flutter app, in a webview that stays on Tamr's origin. `TamrWaiterController` is one waiter for one diner: it loads ahead of the tap and stays loaded between opens.

## Requirements

Flutter 3.38.6 or later, Android API 26+ and iOS 16+.

> **Android needs the Android Gradle Plugin 8.x for now**
>
> The webview plugin this SDK builds on, `flutter_inappwebview_android` 1.1.3, doesn't build on AGP 9, which new apps from Flutter 3.47's template start with. Set the Android plugin back to 8.x in `android/settings.gradle.kts`, as shown below. The line can go once the plugin is fixed upstream.

android/settings.gradle.kts:

```kotlin
id("com.android.application") version "8.13.0" apply false
```

## Install

```sh
flutter pub add tamr_waiter
```

On iOS, Flutter prints a warning that `flutter_inappwebview` doesn't support Swift Package Manager yet. It builds with CocoaPods, Flutter's default, as before.

## Open the waiter

Create one controller where the waiter is likely to be opened (the menu screen, not app start), preload it, and show it on a tap:

```dart
import 'package:tamr_waiter/tamr_waiter.dart';

final waiter = TamrWaiterController(
  appKey: 'tamr_pk_test_…',
  restaurant: 'your-restaurant',
  locale: 'ar',          // optional: branch, appearance, table, tableScan, mode, debug, onLog
)..preload();

// Who the diner is, asked whenever the page needs a fresh token. Return null for "no one".
waiter.setIdentityProvider((reason) async {
  final token = await myBackend.tamrToken(); // your backend signs it
  return token == null ? null : TamrToken(token);
});

// Orders go to your own cart ("Orders go to: the app's cart"): answer each line.
waiter.onCartAdd((change) async => Reply(ok: true, lines: [
  for (final line in change.lines) LineAnswer(lineId: line.lineId, ok: true),
]));

// Everything the page tells you.
waiter.on('payment.completed', (message) {
  final paid = (message as PaymentCompletedMessage).data;
  print('paid ${paid.paymentId}');
});

// On a tap:
TamrWaiterSheet.show(context, controller: waiter);
```

- `TamrWaiterSheet.show(context, controller: …)`: a bottom sheet that handles the keyboard.
- `TamrWaiterPage.open(context, controller: …)`: a full page.
- `TamrWaiterView`: a widget, with loading and retry states.

Dispose the controller when the diner signs out or the screen goes away.

## Who the diner is

`setIdentityProvider(fn)`: `fn(reason)` returns `TamrToken(token)`, `TamrLaunchCode(code)` or `null`, within 15 seconds. See [Diner identity](https://tamr.link/docs/guides/diner-identity).

The Flutter SDK doesn't send your app's id with its calls yet. A key's listed app ids are only logged, never refused, so the waiter works the same without one.

## Voice notes

Optional: without them the waiter works by text.

android/app/src/main/AndroidManifest.xml:

```xml
<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.RECORD_AUDIO"/>
<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS"/>
```

ios/Runner/Info.plist:

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

Then answer `onMicrophonePermission` with your app's own permission flow, for example with permission_handler. A camera request is always refused.

## Payments

With Tamr Pay on, the provider's page opens in the platform's in-app browser (SFSafariViewController, Custom Tabs), never inside the webview, and only when the link is `https`. When the diner comes back, the waiter checks the payment.

## Debug mode

`debug: true` prints every message both ways and the page's own trace to `onLog` or `debugPrint`, and makes the webview inspectable in a debug build of your app. See [Debug mode](https://tamr.link/docs/guides/debugging).

## Methods

The contract's `Text`, `ThemeData` and `Platform` are exported as `TamrText`, `TamrThemeData` and `TamrPlatform`, so they never clash with Flutter's own.

| 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; unload for good | 1.0.0 |
| `setIdentityProvider(fn)` | Who the diner is: TamrToken, TamrLaunchCode or null | 1.0.0 |
| `onCartAdd`, `onCartUpdate`, `onCartRemove` | Answer the waiter's cart proposals, per line | 1.0.0 |
| `on(type`, `listener)` | Everything the page tells your app | 1.0.0 |
| `setLocale`, `setAppearance`, `setText`, `setTheme`, `setContext`, `setStarters`, `setRestrictions` | Kept and sent again whenever the page reloads | 1.0.0 |
| `setGoal(goal)` | The diner's nutrition goal as your app keeps it | 1.1.0 |
| `sendCart(lines)`, `sendMessage(text)`, `newChat()`, `clearIdentity()` | One-off messages, held until the chat is ready | 1.0.0 |
| `requestReview(ReviewRequestData)` | After an order your backend sent: ask the diner to rate each dish | 1.1.0 |
