Android (Kotlin)

The Android SDK is a Kotlin library with no runtime dependencies — no AndroidX, no OkHttp, no Compose, no Material — so it drops into any app, including one that has to pass a bank's dependency review. It hosts the same voice engine as every other Graine SDK and is tested against the same contract: every masking rule, connection-quality threshold and component look is checked against the answers the React Native SDK gives.

Install

// settings.gradle.kts
dependencyResolutionManagement {
    repositories { google(); mavenCentral() }
}
 
// app/build.gradle.kts
dependencies {
    implementation("ai.graine:inapp-android:0.10.3")
}

The source, a sample app and the tests are at github.com/GraineAI/inapp-android.

Android 7.0 (API 24) and up. The library's manifest adds INTERNET, RECORD_AUDIO and MODIFY_AUDIO_SETTINGS for voice, and what a call needs — POST_NOTIFICATIONS, USE_FULL_SCREEN_INTENT, FOREGROUND_SERVICE, FOREGROUND_SERVICE_MICROPHONE, the call screen and its service and receiver (Calls). Its ProGuard rule ships inside it, so there is nothing to copy. The SDK asks for the microphone itself, when a call starts; notifications are yours to ask for.

Two dashboard steps, the same as every platform: give the app its own agent, and add app:// to its Allowed domains under Embed & Widgets.

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 WebRTC module beside the SDK, at the same version:

dependencies {
    implementation("ai.graine:inapp-android:0.10.3")
    implementation("ai.graine:inapp-android-rtc:0.10.3")   // the same version as the SDK
}

Nothing else changes — not your code, the ring, the call screen or the outcomes. The SDK finds the module by itself; without it, calls run on the WebSocket as before, and the SDK keeps no dependencies.

• What the customer notices: a call that holds up better on mobile data and connects as fast as before — it is prepared at the tap, or while the phone rings. Over WebRTC the agent's voice arrives at telephone bandwidth today.
• When WebRTC cannot carry a call, it continues on the WebSocket inside the same ring and screen: no second ring, no error.
• 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: WebRTC's native library, per phone (an app bundle delivers one ABI): about 7.4 MB installed on 64-bit ARM (2.5–3.3 MB to download), 4.3 MB on 32-bit ARM, 8.2–8.4 MB on x86, and about 0.5 MB of classes.
• Permissions and licences: the module's manifest adds ACCESS_NETWORK_STATE (a normal permission, granted at install: nothing is asked); its R8 rules ship inside it. Add graine-inapp-rtc/THIRD-PARTY-NOTICES.md (WebRTC, BSD 3-Clause) to your app's open-source licences.

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

Quickstart

1. Initialise once

class App : Application() {
    override fun onCreate() {
        super.onCreate()
        val graine = GraineInApp.init(this, GraineConfig(
            baseUrl = "https://www.graine.ai",
            publishableKey = "pk_live_…",          // Agent → Embed & Widgets
            appVersion = BuildConfig.VERSION_NAME,
            debug = BuildConfig.DEBUG,             // bridge traffic and the engine's console in logcat
        ))
        graine.registerAction("open_screen") { args ->
            // Main thread. Answer within six seconds, and say what actually happened.
            router.open(args.optString("path"))
            ActionResult.ok("Opened ${args.optString("path")}.")
        }
    }
}

init must run before any bar is created, which Application.onCreate guarantees.

2. Mount the engine and the bar

class KycActivity : Activity() {
    private val graine get() = GraineInApp.get()
 
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.kyc)
        graine.voice.attach(this)   // loads the engine idle: no microphone, nothing dialled
 
        val bar = GraineAgentBarView(this)
        findViewById<FrameLayout>(R.id.root).addView(bar,
            FrameLayout.LayoutParams(MATCH_PARENT, WRAP_CONTENT, Gravity.BOTTOM))
    }
 
    override fun onRequestPermissionsResult(code: Int, permissions: Array<out String>, results: IntArray) {
        if (!graine.voice.onRequestPermissionsResult(code, results))
            super.onRequestPermissionsResult(code, permissions, results)
    }
}

The bar places the call, asks for the microphone when it has to, and says what the network is doing. To draw the call yourself instead, leave the bar out and draw from graine.voice — Your own UI.

3. Tell it what is on screen

graine.setScreen(GraineScreen(
    screen = "kyc_documents",
    title = "Upload your documents",
    journey = GraineScreen.Journey("KYC", step = 2, of = 4, next = "Selfie"),
    fields = listOf(GraineField(
        name = "pan", label = "PAN", value = pan.text.toString(),
        status = if (panValid) GraineField.Status.FILLED else GraineField.Status.INVALID,
        error = panError,
    )),
))

Call it whenever the screen or a field changes; bursts go out as one frame, and an unchanged screen is not resent. Report real values: PAN, Aadhaar, card, phone and email are masked on the device before anything leaves it.

4. Components

Nothing to do: the bar draws the components the agent shows — product lists in five looks, plan comparisons, choices, time slots — and answers the agent with what the customer picked. See Components.

Several activities, one call

Attach the engine once. From then on it follows the customer: whichever of your activities comes to the front, the one engine moves into it and a call in progress carries on. A KYC flow built as one activity per step does not hang up on "Next".

Each activity that should show the agent places its own GraineAgentBarView; a bar created mid-call shows the live call at once. Do not call voice.detach() from onDestroy — that ends the call the next activity is carrying. Backgrounding the app still ends it, after a two-second confirmation.

Jetpack Compose

The views are plain Android views, so Compose hosts them with AndroidView:

Box(Modifier.fillMaxSize()) {
    AppContent()
    AndroidView(
        factory = { GraineAgentBarView(it) },
        modifier = Modifier.align(Alignment.BottomCenter).padding(12.dp),
    )
}

Java

Every entry point works from Java with only the arguments you need: new GraineConfig(baseUrl, publishableKey), ActionResult.ok("Done."), new GraineScreen("kyc_documents"). GraineListener has default methods, so a Java listener overrides only the callbacks it wants.

Calls: the ring, the call screen, the screen off

A WhatsApp-style call with your agent: the customer calls it, or your server rings the customer with a push — a call notification that fills a locked screen, Answer and Decline, the call going on with the screen off. calls runs the call's audio natively in a foreground service, with the SDK's own call screen (or yours). The library's manifest brings everything it needs. 0.6.0

Add Firebase to your app; the SDK registers for pushes itself. With Firebase Cloud Messaging in the app (google-services.json, its Gradle plugin and com.google.firebase:firebase-messaging), the SDK's own messaging service rings each call push and receives every new token, and the SDK reads the current token when it starts. No messaging service of yours.

val calls = GraineInApp.get().calls
calls.configure(GraineCallsConfig(displayName = "Acme Assistant", smallIcon = R.drawable.ic_call))
calls.addListener(object : GraineCallListener {
    override fun onCallOutcome(callId: String, outcome: GraineCallOutcome) = myServer.report(callId, outcome.wire)
})
 
// A "Call us" button
calls.startCall(activity, reason = "kyc_help")

Already have your own FirebaseMessagingService? It outranks the SDK's (declared at priority -1) and receives every message, so hand Graine's over — two lines:

override fun onNewToken(token: String) = GraineCalls.onNewToken(this, token)
override fun onMessageReceived(message: RemoteMessage) {
    if (GraineCalls.handlePush(this, message.data)) return
    // …your own messages
}

The push your server sends, the call screen and what to test: In-app calling. With the WebRTC module in the app, both directions carry their audio over WebRTC; GraineCallsConfig(callTransport = …) chooses and calls.transport says which one ran. 0.9.0

Not using calls? The library's manifest adds what a call needs to every app that includes it. On Android 14 and later, Google Play asks apps that declare USE_FULL_SCREEN_INTENT or FOREGROUND_SERVICE_MICROPHONE to explain why in the Play Console. An app that never places a call removes them, and the call's microphone service, in its own AndroidManifest.xml:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools">
    <uses-permission android:name="android.permission.USE_FULL_SCREEN_INTENT" tools:node="remove" />
    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_MICROPHONE" tools:node="remove" />
    <application>
        <service android:name="ai.graine.inapp.GraineCallService" tools:node="remove" />
    </application>
</manifest>

Reference

GraineConfig

GraineInApp

GraineVoice

GraineCalls

Main thread, except handlePush, which is safe from the messaging service's thread. 0.6.0

GraineCallsConfig(displayName, smallIcon, ringtone, callActivity, ringTimeoutMs, callTransport) — the name on the ring and the call screen ("Assistant" unless you set one; a push's caller_name wins), a monochrome notification icon, the ring (the phone's ringtone by default), your own call screen instead of GraineCallActivity, how long a ring lasts before it is missed (30 s), and what carries the calls' audio: GraineCallTransport.AUTO (the default — WebRTC when the module is in the app), WEBSOCKET or WEBRTC.

GraineCallListener — onIncomingCall, onCallState, onCallOutcome(callId, outcome) (outcome.wire: answered, declined, missed, ended, failed; outcome.endReason with ended, outcome.error saying why), onCallCaption, onAgentSpeaking and onCallControls. Every method is optional; all are called on the main thread.

GraineAgentBarView

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, add a GraineChatView, or open GraineChatActivity.open(context) — Chat. A chat of your own reads chat.reconnecting (true while a dropped chat is being made again — say Reconnecting…, not Offline), and lays the conversation out as the SDK's window does with ChatRows.build(messages) — a bubble per message, one Voice call row per earlier call, a day line where the day changes. 0.9.0

Each property overrides one thing:

GraineWidgetView is the component renderer on its own, for a layout that draws components somewhere other than the bar.

GraineListener

Every callback is optional.

Troubleshooting

Next steps