iOS (Swift)

The iOS SDK is a Swift package with no dependencies, for iOS 15 and up. It hosts the same voice engine as every other Graine SDK — in a WKWebView it owns, one invisible point big — so every audio fix reaches your app without a release. Its rules (masking, connection quality, component looks, placement, friction) are tested against the answers the React Native SDK gives.

Install

In Xcode: File → Add Package Dependencies…, enter

https://github.com/GraineAI/inapp-ios

and add the GraineInApp library to your app target — that repository is the package's source and tests. In a Package.swift:

.package(url: "https://github.com/GraineAI/inapp-ios", from: "0.10.3")

Add the microphone reason to Info.plist — your app is the one asking:

<key>NSMicrophoneUsageDescription</key>
<string>Used to talk to the in-app assistant.</string>

In the dashboard, give the app its own agent and add app:// to its Allowed domains under Embed & Widgets. Without it, every session is refused.

App Store privacy. The SDK ships a privacy manifest that declares the required-reason APIs it calls — system uptime, for timing, and UserDefaults, for its call settings — and no tracking; Xcode adds it to your app's privacy report. What your app collects through the agent (the customer's voice, and what you report to it) is yours to declare in your App Store privacy details.

Calls over WebRTC (optional)

The native calls — the customer calling the agent, and a call Graine rang — carry their audio over WebRTC when you add the GraineInAppRTC package beside GraineInApp, at the same version. In Xcode, add https://github.com/GraineAI/inapp-ios-rtc and its GraineInAppRTC library to the same target; in a Package.swift:

.package(url: "https://github.com/GraineAI/inapp-ios-rtc", from: "0.10.3")

With CocoaPods, pod 'GraineInAppRTC', :git => 'https://github.com/GraineAI/inapp-ios-rtc.git', :tag => '0.10.3'. One Info.plist entry, and nothing else: NSCameraUsageDescription — WebRTC contains camera code, and App Store processing refuses a build that references the camera without it (ITMS-90683: the build never reaches TestFlight). Calls are audio only; say so, for example Calls are audio only. The camera is never turned on. No code, no capability — the calls find the module by themselves (a build that strips code nothing references can call GraineRTC.install() at launch). GraineInApp itself keeps no dependencies, and an app that does not add the module never downloads it.

• What the customer notices: the same ring, the same call screen, the same Connecting…. On a weak or changing network the agent's voice holds up instead of stalling and catching up. Over WebRTC it arrives at telephone bandwidth today.
• When WebRTC cannot carry a call, it continues on the WebSocket inside the same call — no second ring.
• The dashboard decides last: the agent's In-app call audio setting (Calls & scheduling) — WebRTC (recommended) or Standard — can move every install's calls to the WebSocket from their next start, without a release.
• Size: about 12 MB more installed on an arm64 iPhone, about 6 MB more to download. Add the package's THIRD-PARTY-NOTICES.md (WebRTC, BSD 3-Clause) to your app's open-source notices.

The choice in code, and which one ran: Calls over WebRTC.

Quickstart

1. Configure once, at launch

import GraineInApp
 
@main
struct MyApp: App {
    init() {
        GraineInApp.configure(GraineConfig(
            baseUrl: "https://www.graine.ai",
            publishableKey: "pk_live_…",     // Agent → Embed & Widgets
            appVersion: "2.4.0"
        ))
        GraineInApp.shared.registerAction("open_screen") { args in
            // Main thread. Answer within six seconds, and say what actually happened.
            router.open(args["path"] as? String)
            return .ok("Opened the screen.")
        }
    }
    var body: some Scene { WindowGroup { RootView() } }
}

2. Add the bar

RootView()
    .overlay(GraineAgentBar(
        initialOffset: savedOffset,
        onPlacementChange: { savedOffset = $0 }   // where the customer dragged it; the SDK stores nothing
    ))
    .overlay(alignment: .bottom) {
        GraineWidgetView().padding(.horizontal, 12).padding(.bottom, 96)   // the components the agent shows
    }

The bar mounts the voice engine in the key window the first time it appears, places the call, asks for the microphone, says what the network is doing, can be dragged, and rises above the keyboard. The engine lives in the window, not in a screen, so a call carries on while the customer moves through your app.

3. Tell it what is on screen

let graine = GraineInApp.shared
graine.identify(["name": user.firstName, "plan": user.plan])   // nil on sign-out
graine.setScreen(GraineScreen(
    screen: "kyc_documents",
    title: "Upload your documents",
    journey: .init(name: "KYC", step: 2, of: 4),
    fields: [GraineField(name: "pan", label: "PAN", value: pan, status: .invalid, error: "Not recognised")]
))

Report real values: PAN, Aadhaar, card, phone and email are masked on the device before anything leaves it. GraineMasking.addRule(pattern:token:) adds your own shapes.

4. Components

On iOS the bar does not draw components: GraineWidgetView() does, wherever you place it — above the bar, as in step 2. It draws every component the agent shows, in the brand's design, and answers the agent with what the customer picked. See Components.

UIKit

The bar and the component view are SwiftUI views; a UIKit app hosts them in a UIHostingController. Without the bar, mount the engine yourself — GraineInApp.shared.voice.attach(to: window), once — and drive the call with start(), end() and setMuted(_:).

A handler that takes time

graine.registerAction("upload_document", deferred: { args, done in
    upload(args) { ok in done(ok ? .ok("Uploaded.") : .error("The upload failed.")) }
})

The agent waits for done, up to six seconds; after that it is told the app did not answer.

Calls: CallKit and VoIP pushes

A WhatsApp-style call with your agent on the system's own call screen: the customer calls it, or your server rings the customer with a VoIP push — answered from the lock screen, going on with the screen off. calls runs the call's audio in your app's own process, so it works with CallKit, where a web view cannot. 0.6.0

let calls = GraineInApp.shared.calls
calls.configure(GraineCallsConfig(displayName: "Acme Assistant"))
calls.enableVoIPPushes { token in myServer.saveVoipToken(token) }   // at launch, every launch
calls.addListener(self)                                             // outcomes, for your server
calls.startCall(reason: "card_blocked")                             // the customer calls the agent

Push Notifications and Background Modes (Audio, Voice over IP) are required. The setup, the push your server sends and what to test: In-app calling. With the GraineInAppRTC package in the app, both directions carry their audio over WebRTC; GraineCallsConfig(callTransport:) chooses and calls.transport says which one ran. 0.9.0

Reference

GraineConfig

GraineInApp

GraineVoice

An ObservableObject, so your own SwiftUI can draw from it — a full example, with every state to draw, is in Your own UI.

GraineCalls

An ObservableObject, main thread. 0.6.0

GraineCallsConfig(displayName:ringtoneSound:iconTemplateImageData:includesCallsInRecents:ringTimeout:callTransport:) — the name the call shows (your app's name if you leave it empty; a push's caller_name wins), a ring sound in your bundle, a template icon for the system call screen, whether calls appear in Recents (off by default), the seconds before an unanswered ring is missed (30, and at least 1), and what carries the calls' audio: .auto (the default — WebRTC when GraineInAppRTC is in the app), .websocket or .webrtc.

GraineCallsListener — onIncomingCall(_:), onCallState(_:callId:) and onCallOutcome(_:callId:): .answered, .declined, .missed, .ended(.local | .remote | .failed) or .failed(message), the message saying why, for your logs. Every method is optional.

GraineCallView() is a ready call screen for while your app is open.

GraineAgentBar

The bar is drawn in the brand's design, exactly as the dashboard's Garage previews it: the design's surface, corners and shadow (a hard offset for Neo-Brutalist, frosted for Liquid Glass), the accent avatar with the launcher glyph, the name and status in the design's typeface with a meter that moves at the design's pace, the microphone, the hang-up and the caption card — and the dashboard's loader while the call connects, reconnects or the agent thinks. The SDK downloads the design's typeface from Graine and registers it itself; there is nothing to bundle and nothing to configure. 0.3.0 — Your design

From 0.7.0 the bar carries the chat too: where the dashboard offers both, it shows a switch and opens the chat window in your design. To place the chat yourself, use GraineChatView (SwiftUI) or GraineChatViewController (UIKit) — Chat. To draw a chat of your own, GraineChatRows.build(turns) lays the conversation out as the SDK's window does — a bubble per message, one Voice call row per earlier call, a day line where the day changes — and chat.clear() empties the chat on screen (only the screen: the conversation goes on). 0.9.0

GraineListener has the same events as on Android — session ready, call state, captions, components, ended, microphone denied, quality, network, reconnecting, transport, actions, friction and errors — each with a default, so you implement only what you use.

Troubleshooting

Next steps