Android Integration Guide

dependencies {
    implementation("ai.revrag:embed-android:1.0.8")
}

<!-- Auto-added by the SDK via manifest merger -->
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
<uses-permission android:name="android.permission.BLUETOOTH" android:maxSdkVersion="30" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />

// MyApplication.kt
import android.app.Application
import ai.revrag.embed.android.EmbedSDK

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()

        EmbedSDK.initialize(
            context  = this,
            apiKey   = "YOUR_REVRAG_API_KEY",
            embedUrl = null   // optional — custom backend URL; leave null for default
        ) { result ->
            if (result.success) Log.d("Revrag", "SDK ready")
            else                Log.e("Revrag", "Init failed: ${result.error}")
        }
    }
}

<application
    android:name=".MyApplication"
    ... >

import ai.revrag.embed.android.EmbedSDK
import ai.revrag.embed.android.EventKeys

EmbedSDK.event(
    EventKeys.USER_DATA,
    mapOf(
        "app_user_id" to "user_123",       // required
        "name"        to "Jane Doe",        // optional
        "email"       to "jane@email.com"   // optional
    )
)

// MainActivity.kt
import ai.revrag.embed.android.EmbedProvider
import androidx.activity.ComponentActivity

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        EmbedProvider.attach(
            activity   = this,
            appUserId  = "user_123",
            appVersion = BuildConfig.VERSION_NAME
        ) {
            // Your existing root composable — no changes needed
            MyAppTheme {
                AppNavigation()
            }
        }
    }
}

setContent {
    MyAppTheme {
        Box(modifier = Modifier.fillMaxSize()) {
            YourMainScreen()

            EmbedProviderComposable(
                currentScreen = "HomeScreen",
                appUserId     = "user_123",
                appVersion    = BuildConfig.VERSION_NAME
            )
        }
    }
}

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        EmbedProvider.attach(
            activity   = this,
            appUserId  = "user_123",
            appVersion = BuildConfig.VERSION_NAME
        ) {
            val navController = rememberNavController()

            NavHost(navController = navController, startDestination = "home") {
                composable("home")         { HomeScreen() }
                composable("search")       { SearchScreen() }
                composable("product/{id}") { ProductScreen() }
                composable("cart")         { CartScreen() }
                composable("checkout")     { CheckoutScreen() }
                composable("profile")      { ProfileScreen() }
            }
        }
    }
}

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        EmbedProvider.attach(
            activity   = this,
            appUserId  = "user_123",
            appVersion = BuildConfig.VERSION_NAME
        ) {
            val homeNavController    = rememberNavController()
            val exploreNavController = rememberNavController()
            val profileNavController = rememberNavController()

            var selectedTab by remember { mutableStateOf(0) }

            Scaffold(
                bottomBar = {
                    BottomNavBar(
                        selected = selectedTab,
                        onSelect = { selectedTab = it }
                    )
                }
            ) { padding ->
                Box(Modifier.padding(padding)) {
                    when (selectedTab) {
                        0 -> TabNavHost(navController = homeNavController,    startRoute = "home")
                        1 -> TabNavHost(navController = exploreNavController, startRoute = "explore")
                        2 -> TabNavHost(navController = profileNavController, startRoute = "profile")
                    }
                }
            }
        }
    }
}

// Call this whenever the screen changes
EmbedSDK.event(
    EventKeys.SCREEN_STATE,
    mapOf("screen" to "ProductDetail", "action" to "enter")
)

class ProductFragment : Fragment() {
    override fun onResume() {
        super.onResume()
        EmbedSDK.event(EventKeys.SCREEN_STATE, mapOf("screen" to "ProductDetail"))
    }
}

@Composable
fun CheckoutScreen() {
    LaunchedEffect(Unit) {
        EmbedSDK.event(EventKeys.SCREEN_STATE, mapOf("screen" to "Checkout"))
    }
    // your content
}

NavHost(navController = rootNavController, startDestination = "main") {

    // Tab container
    composable("main") {
        MainTabsScreen()
    }

    // Checkout flow — nested graph
    navigation(startDestination = "cart", route = "checkout_flow") {
        composable("cart")         { CartScreen() }
        composable("payment")      { PaymentScreen() }
        composable("confirmation") { ConfirmationScreen() }
    }

    // Settings — separate stack
    composable("settings") { SettingsScreen() }
}

EmbedProvider.attach(
    activity         = this,
    appUserId        = "user_123",
    appVersion       = BuildConfig.VERSION_NAME,
    visibilityConfig = EmbedButtonVisibilityConfig(
        allowedScreens  = listOf("home", "product", "cart"),
        excludedScreens = listOf("login", "splash", "onboarding")
    )
) { /* content */ }

visibilityConfig = EmbedButtonVisibilityConfig(
    groups = listOf(
        EmbedButtonGroupConfig(
            id          = "checkout-flow",
            screens     = listOf("cart", "payment", "confirmation"),
            continuity  = EmbedButtonContinuity.CONTINUOUS,
            delayMs     = 500L,
            delayPolicy = EmbedButtonDelayPolicy.ONCE_PER_GROUP_ENTRY
        )
    )
)

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

// Identity comes from the stored app_user_id — send USER_DATA first.
EmbedSDK.event(EventKeys.USER_DATA, mapOf("app_user_id" to "user_123"))

// Start a call: handles mic + Bluetooth permission, connects, installs the reconnect provider.
EmbedSDK.startCall(activity) { started ->
    // true once the call started; false if it could not.
    // Failure reasons are reported to Revrag (analytics "error"), not returned here.
}

EmbedSDK.endCall()        // End the active call. Emits AGENT_DISCONNECTED.
EmbedSDK.isCallActive()   // Boolean — is a call currently connected?

EmbedSDK.collapseWidget()  // Collapse the card. Fires agent_tap_to_close. Does NOT end a call.
EmbedSDK.isWidgetExpanded  // StateFlow<Boolean> — reactive expanded/collapsed state.

// User identity (required before first call)
EmbedSDK.event(EventKeys.USER_DATA, mapOf("app_user_id" to "user_123"))

// Custom analytics event
EmbedSDK.event(EventKeys.ANALYTICS_DATA, mapOf("event_name" to "checkout_started"))

// Manual screen state
EmbedSDK.event(EventKeys.SCREEN_STATE, mapOf("screen" to "CheckoutScreen", "action" to "enter"))

// Register in onCreate or onStart
val onConnected: AgentEventCallback = { _ ->
    // e.g. pause background music
    Log.d("Revrag", "Agent call started")
}
val onDisconnected: AgentEventCallback = { payload ->
    val duration = (payload["metadata"] as? Map<*, *>)?.get("callDuration") as? Int ?: 0
    Log.d("Revrag", "Call lasted ${duration}s")
}

EmbedSDK.onAgent(AgentEvent.AGENT_CONNECTED,    onConnected)
EmbedSDK.onAgent(AgentEvent.AGENT_DISCONNECTED, onDisconnected)

// Always de-register in onDestroy
override fun onDestroy() {
    super.onDestroy()
    EmbedSDK.offAgent(AgentEvent.AGENT_CONNECTED,    onConnected)
    EmbedSDK.offAgent(AgentEvent.AGENT_DISCONNECTED, onDisconnected)
}

val cb: EventCallback = { data -> Log.d("Revrag", "User data: $data") }
EmbedSDK.on(EventKeys.USER_DATA, cb)
EmbedSDK.off(EventKeys.USER_DATA, cb)

// Track a custom event
EmbedSDK.trackEvent("product_viewed", mapOf("product_id" to "SKU-123"))

// Track a form interaction
EmbedSDK.trackFormEvent(
    formId    = "checkout_form",
    eventType = "submit",
    formData  = mapOf("step" to "payment")
)

// Track a rage-click
EmbedSDK.trackRageClick(
    elementId   = "btn_add_to_cart",
    coordinates = Pair(x, y),
    clickCount  = 5,
    elementType = "Button"
)

// Check microphone permission status
EmbedSDK.checkPermissions(context) { granted ->
    if (!granted) showMicEducationDialog()
}

EmbedAnalyticsEvents.GEN_TOOL_TRIGGERED          // "gen_tool_triggered"
EmbedAnalyticsEvents.POPUP_MESSAGE_VISIBLE       // "popup_message_visible"
EmbedAnalyticsEvents.AGENT_TAP_TO_OPEN           // "agent_tap_to_open"
EmbedAnalyticsEvents.AGENT_TAP_TO_CLOSE          // "agent_tap_to_close"
EmbedAnalyticsEvents.AGENT_VISIBLE               // "agent_visible"
EmbedAnalyticsEvents.AGENT_CONVERSATION_STARTED  // "agent_conversation_started"
EmbedAnalyticsEvents.RAGE_CLICK                  // "rage_click"
EmbedAnalyticsEvents.MICROPHONE_PERMISSION_ALLOW // "microphone_permission_allow"
EmbedAnalyticsEvents.FORM_EVENT                  // "form_event"
EmbedAnalyticsEvents.ERROR                       // "error"

EmbedSDK.on(EventKeys.ANALYTICS_DATA) { data ->
    when (data["event_name"]) {
        EmbedAnalyticsEvents.AGENT_TAP_TO_OPEN -> { /* widget opened */ }
        EmbedAnalyticsEvents.ERROR             -> { /* SDK error */ }
    }
}

EmbedSDK.setAppVersion("2.0.0")        // override the reported app version
EmbedSDK.setCurrentFlow("onboarding")  // tag events with a logical flow name
EmbedSDK.isInitialized()               // Boolean snapshot
EmbedSDK.isInitializedFlow             // StateFlow<Boolean> — collect in Composables
EmbedSDK.widgetConfig                  // StateFlow<WidgetConfig?> — reactive dashboard config

// after EmbedSDK.initialize:
SdkLifecycleListener.register()                  // log every SDK event to Logcat
SdkLifecycleListener.register { name, data ->     // or handle them yourself
    myAnalytics.track(name, data)
}

// on teardown:
SdkLifecycleListener.unregister()

import ai.revrag.embed.android.EmbedAnalyticsEvents
import ai.revrag.embed.android.EmbedSDK
import ai.revrag.embed.android.EventCallback
import ai.revrag.embed.android.EventKeys
import android.util.Log

/**
 * Listens to the lifecycle / analytics events the SDK fires on its own (widget taps,
 * call start, permission prompts, rage-clicks, etc.).
 *
 * All of these are emitted as `ANALYTICS_DATA` events carrying an `event_name`, so a single
 * `EmbedSDK.on(EventKeys.ANALYTICS_DATA)` listener receives them all — we dispatch by `event_name`.
 */
object SdkLifecycleListener {

    private const val TAG = "SdkLifecycle"

    /** Held so we can pass the SAME reference to off() when unregistering. */
    private var callback: EventCallback? = null

    /**
     * Start listening. Idempotent — calling twice keeps a single registration.
     * @param onEvent optional handler for every event (name + full payload); defaults to logging.
     */
    fun register(onEvent: ((name: String, data: Map<String, Any?>) -> Unit)? = null) {
        if (callback != null) return
        val cb: EventCallback = { data ->
            val name = data["event_name"] as? String ?: "unknown"
            Log.d(TAG, "${label(name)} → $data")
            onEvent?.invoke(name, data)
        }
        callback = cb
        EmbedSDK.on(EventKeys.ANALYTICS_DATA, cb)
        Log.d(TAG, "Registered — listening for SDK lifecycle events")
    }

    /** Stop listening. Safe to call when not registered. */
    fun unregister() {
        callback?.let { EmbedSDK.off(EventKeys.ANALYTICS_DATA, it) }
        callback = null
        Log.d(TAG, "Unregistered")
    }

    /** Human-readable label for a known SDK event name (falls back to the raw name). */
    private fun label(name: String): String = when (name) {
        EmbedAnalyticsEvents.AGENT_TAP_TO_OPEN           -> "🔵 Widget expanded (agent_tap_to_open)"
        EmbedAnalyticsEvents.AGENT_TAP_TO_CLOSE          -> "⚪ Widget collapsed (agent_tap_to_close)"
        EmbedAnalyticsEvents.AGENT_VISIBLE               -> "👁️ Widget became visible (agent_visible)"
        EmbedAnalyticsEvents.AGENT_CONVERSATION_STARTED  -> "🎙️ Call started (agent_conversation_started)"
        EmbedAnalyticsEvents.POPUP_MESSAGE_VISIBLE       -> "💬 Popup/tooltip shown (popup_message_visible)"
        EmbedAnalyticsEvents.MICROPHONE_PERMISSION_ALLOW -> "🎤 Mic permission granted (microphone_permission_allow)"
        EmbedAnalyticsEvents.GEN_TOOL_TRIGGERED          -> "🛠️ Agent tool triggered (gen_tool_triggered)"
        EmbedAnalyticsEvents.RAGE_CLICK                  -> "😡 Rage click (rage_click)"
        EmbedAnalyticsEvents.FORM_EVENT                  -> "📝 Form event (form_event)"
        EmbedAnalyticsEvents.ERROR                       -> "❌ SDK error (error)"
        else                                             -> "ℹ️ $name"
    }
}

fun onUserLogout() {
    EmbedSDK.clearStorageCache()
}

EmbedSDK.initialize(context, apiKey = "YOUR_KEY") { result ->
    Log.d("Revrag", "success=${result.success} error=${result.error}")
}

lifecycleScope.launch {
    EmbedSDK.isInitializedFlow.collect { ready ->
        Log.d("Revrag", "SDK ready: $ready")
    }
}

"Home" ≠ "home"  — they must match exactly

NoClassDefFoundError: io.ktor.client.plugins.contentnegotiation.ContentNegotiation

plugins {
    kotlin("android") version "2.0.21" apply false
}

# Clear cache and retry
./gradlew --refresh-dependencies

repositories {
    google()
    mavenCentral()   // ← must be present
}

// ❌ Wrong — nested inside a sized Box
Box(modifier = Modifier.size(200.dp)) {
    EmbedProviderComposable(...)
}

// ✅ Correct — use EmbedProvider.attach() which handles root placement automatically
EmbedProvider.attach(activity = this, appUserId = "user_123") {
    YourContent()
}

EmbedSDK.checkPermissions(context) { granted ->
    if (!granted) {
        startActivity(
            Intent(Settings.ACTION_APPLICATION_DETAILS_SETTINGS).apply {
                data = Uri.fromParts("package", packageName, null)
            }
        )
    }
}

fun onUserLogout() {
    EmbedSDK.clearStorageCache()
}