iOS Integration Guide

https://github.com/RevRag-ai/embed-native

# Podfile
pod 'RevragEmbed', '~> 1.0'

pod install
open YourApp.xcworkspace

<key>NSMicrophoneUsageDescription</key>
<string>This app uses the microphone to talk with the AI agent.</string>

// YourApp.swift
import SwiftUI
import RevragEmbed

@main
struct YourApp: App {

    init() {
        Task {
            await EmbedSDK.shared.initialize(apiKey: "YOUR_REVRAG_API_KEY")
        }
    }

    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}

// AppDelegate.swift
import UIKit
import RevragEmbed

@main
class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        Task {
            await EmbedSDK.shared.initialize(apiKey: "YOUR_REVRAG_API_KEY")
        }
        return true
    }
}

EmbedSDK.shared.event(.userData, data: [
    "app_user_id": "user_123",       // required
    "name":        "Jane Doe",        // optional
    "email":       "jane@email.com"   // optional
])

// ContentView.swift
import SwiftUI
import RevragEmbed

struct ContentView: View {
    var body: some View {
        NavigationStack {
            HomeView()
        }
        .embedProvider(
            appUserId:  "user_123",
            appVersion: Bundle.main.releaseVersionNumber ?? "1.0"
        )
    }
}

import RevragEmbed
import SwiftUI

// In viewDidLoad of your root UIViewController
let embedView = UIHostingController(rootView:
    EmbedButton(appUserId: "user_123")
)
embedView.view.backgroundColor = .clear
addChild(embedView)
view.addSubview(embedView.view)
embedView.view.frame = view.bounds
embedView.view.autoresizingMask = [.flexibleWidth, .flexibleHeight]
embedView.didMove(toParent: self)

struct HomeView: View {
    var body: some View {
        List { /* content */ }
            .onAppear {
                NotificationCenter.default.post(
                    name:     NSNotification.Name("EmbedViewDidAppear"),
                    object:   nil,
                    userInfo: ["screen": "Home"]
                )
            }
    }
}

struct ProductView: View {
    let productId: String

    var body: some View {
        ScrollView { /* content */ }
            .onAppear {
                NotificationCenter.default.post(
                    name:     NSNotification.Name("EmbedViewDidAppear"),
                    object:   nil,
                    userInfo: ["screen": "ProductDetail"]
                )
            }
    }
}

struct ContentView: View {
    var body: some View {
        NavigationStack {
            HomeView()
        }
        .embedProvider(appUserId: "user_123", appVersion: "1.0")
    }
}

struct ContentView: View {
    var body: some View {
        TabView {
            NavigationStack {
                HomeView()
            }
            .tabItem { Label("Home", systemImage: "house") }

            NavigationStack {
                ExploreView()
            }
            .tabItem { Label("Explore", systemImage: "magnifyingglass") }

            NavigationStack {
                ProfileView()
            }
            .tabItem { Label("Profile", systemImage: "person") }
        }
        // Provider goes here — outside TabView — so button floats over all tabs
        .embedProvider(appUserId: "user_123", appVersion: "1.0")
    }
}

struct CheckoutView: View {
    var body: some View {
        VStack { /* content */ }
            .onAppear {
                NotificationCenter.default.post(
                    name:     NSNotification.Name("EmbedViewDidAppear"),
                    object:   nil,
                    userInfo: ["screen": "Checkout"]
                )
            }
            .onDisappear {
                // Optional — fires SCREEN_STATE with action: "exit"
                NotificationCenter.default.post(
                    name:     NSNotification.Name("EmbedViewDidDisappear"),
                    object:   nil,
                    userInfo: ["screen": "Checkout"]
                )
            }
    }
}

struct ContentView: View {
    let navController: UINavigationController

    var body: some View {
        UIKitNavigationWrapper(navController: navController)
            .embedProvider(
                appUserId:            "user_123",
                appVersion:           "1.0",
                navigationController: navController   // ← automatic tracking
            )
    }
}

ContentView()
    .embedProvider(
        appUserId:  "user_123",
        appVersion: "1.0",
        visibilityConfig: EmbedButtonVisibilityConfig(
            allowedScreens:  ["Home", "Product", "Cart"],
            excludedScreens: ["Login", "Splash", "Onboarding"]
        )
    )

visibilityConfig: EmbedButtonVisibilityConfig(
    groups: [
        EmbedButtonGroupConfig(
            id:          "checkout-flow",
            screens:     ["Cart", "Payment", "Confirmation"],
            continuity:  .continuous,
            delayMs:     0.5,
            delayPolicy: .oncePerGroupEntry
        )
    ]
)

1. Screen is in excludedScreens               →  always HIDDEN  (strongest rule)
2. allowedScreens and groups are both empty   →  always VISIBLE
3. Screen is in allowedScreens or any group   →  VISIBLE
4. Otherwise                                  →  HIDDEN

// User identity (required before first call)
EmbedSDK.shared.event(.userData, data: ["app_user_id": "user_123"])

// Custom analytics event
EmbedSDK.shared.event(.analyticsData, data: ["event_name": "checkout_started"])

// Manual screen state
EmbedSDK.shared.event(.screenState, data: ["screen": "CheckoutScreen", "action": "enter"])

import RevragEmbed

class CallManager {
    private var connectedId:    UUID?
    private var disconnectedId: UUID?

    func startListening() {
        connectedId = EmbedSDK.shared.onAgent(.agentConnected) { _ in
            // e.g. pause background audio
            print("Call started")
        }
        disconnectedId = EmbedSDK.shared.onAgent(.agentDisconnected) { payload in
            let duration = (payload["metadata"] as? [String: Any])?["callDuration"] as? Int ?? 0
            print("Call lasted \(duration)s")
        }
    }

    func stopListening() {
        if let id = connectedId    { EmbedSDK.shared.offAgent(.agentConnected,    id: id) }
        if let id = disconnectedId { EmbedSDK.shared.offAgent(.agentDisconnected, id: id) }
    }
}

// Track a custom event
EmbedSDK.shared.trackEvent("product_viewed", properties: ["product_id": "SKU-123"])

// Track a form interaction
EmbedSDK.shared.trackFormEvent(
    formId:    "checkout_form",
    eventType: "submit",
    formData:  ["step": "payment"]
)

// Track a rage-click
EmbedSDK.shared.trackRageClick(
    elementId:   "btn_add_to_cart",
    coordinates: CGPoint(x: 200, y: 450),
    clickCount:  5,
    elementType: "UIButton"
)

// Check microphone permission status
EmbedSDK.shared.checkMicPermission { granted in
    if !granted { self.showMicEducationAlert() }
}

func onUserLogout() {
    EmbedSDK.shared.clearStorageCache()
}

This app has crashed because it attempted to access privacy-sensitive data
without a usage description.

[RevragEmbed] 🚀 Stage 1 — initialize() called
[RevragEmbed] 🌐 Stage 3 — calling GET /embedded-agent/initialize …
[RevragEmbed] ❌ Initialization failed: <error message>

print(EmbedSDK.shared.isInitialized)  // should be true

// What you post in .onAppear:
userInfo: ["screen": "ProductDetail"]

// Must match exactly in visibilityConfig:
allowedScreens: ["Home", "ProductDetail"]   // ✅ correct
allowedScreens: ["Home", "productdetail"]   // ❌ case mismatch
allowedScreens: ["Home", "Product Detail"]  // ❌ space mismatch

// ❌ Wrong — provider scoped to one tab only
TabView {
    HomeView()
        .embedProvider(appUserId: "user_123")  // hidden on all other tabs
        .tabItem { ... }
}

// ✅ Correct — provider wraps the entire TabView
TabView {
    HomeView().tabItem { ... }
    ProfileView().tabItem { ... }
}
.embedProvider(appUserId: "user_123")  // visible on all tabs

// ✅ Add this to every screen's .onAppear
.onAppear {
    NotificationCenter.default.post(
        name:     NSNotification.Name("EmbedViewDidAppear"),
        object:   nil,
        userInfo: ["screen": "YourScreenName"]
    )
}

func onUserLogout() {
    EmbedSDK.shared.clearStorageCache()
}