---
title: "Install and configure the Android SDK"
description: "Install the versioned Android SDK, configure identity and microphone permission, and build the example app."
last_updated: "2026-10-07T12:31:33+03:00"
---
# Install and configure the Android SDK

Source: https://busymate.ai/ru/docs/guides/android-sdk
Last modified: 2026-10-07T12:31:33+03:00
Integrate Busymate AI using the official Android SDK distribution **1.0.0**. Source, configuration reference and a buildable demo live in the [public repository](https://github.com/serebano/busymate-ai-sdk-android/tree/1.0.0). Identity uses protocol v2 / bridge build 2.0.0; microphone uses protocol v1 / adapter 1.0.0.

## 1. Install the pinned version

1. Clone `https://github.com/serebano/busymate-ai-sdk-android.git` at tag `1.0.0` into `vendor/busymate-ai-sdk-android`. Include its `sdk/` directory as the `:busymate-sdk` project in your Gradle settings and add `implementation(project(":busymate-sdk"))`. This release uses source-module installation; do not substitute an unpublished Maven coordinate. Use Java 17, Gradle 8.9, Android Gradle Plugin 8.7.3, Kotlin 2.0.21 and compileSdk 35; the SDK supports minSdk 23. See the repository README for exact Gradle commands and dependency versions.
2. Use the chat URL and assistant slug from your workspace. Preserve the URL's supported parameters and set `channel=android`.
3. Read the [versioned installation instructions](https://github.com/serebano/busymate-ai-sdk-android/blob/1.0.0/README.md) before wiring callbacks.

## 2. Install before loading chat

Configure account and backend callbacks and install `BusymateBridge` before the first navigation. The generated starter takes callbacks from your host; implement them using your existing authenticated backend client.

```kotlin
// Gradle installation + lifecycle: https://busymate.ai/docs/guides/android-sdk
// Source: https://github.com/serebano/busymate-ai-sdk-android/tree/1.0.0
import android.webkit.WebView
import ai.busymate.bridge.BusymateBridge

fun installAssistant(
  webView: WebView,
  account: () -> String?,
  mint: (Map<String, Any?>, (BusymateBridge.MintResult) -> Unit) -> Unit
) {
  BusymateBridge.install(webView, BusymateBridge.Config(
    assistant = "your-assistant",
    origins = listOf("https://your-assistant.busymate.ai"),
    account = account,
    mint = mint
  ))
  // mint calls YOUR authenticated backend with request["nonce"], then done(result).
  // Backend endpoint: https://YOUR-PRODUCT-DOMAIN/api/bmai/identity
  webView.loadUrl("https://your-assistant.busymate.ai/?channel=android")
}
// Microphone: declare INTERNET + RECORD_AUDIO; construct and retain
// BusymateMicrophone in Activity.onCreate BEFORE STARTED/loadUrl; forward
// WebChromeClient.onPermissionRequest. See the guide for renderer recovery.
// Call BusymateBridge.accountChanged() on login/logout/account changes.
```

Allow only exact HTTPS origins, without wildcards. The identity bridge adds the assistant's platform origin; the microphone adapter receives its own explicit origin set. Include the actual requesting chat frame origin, not just the outer page's origin.

## 3. Configure every supported callback

| Setting | Purpose |
| --- | --- |
| `assistant` | Required assistant slug. |
| `origins` | Extra exact HTTPS chat origins. |
| `account` | Current account ID or nil/null when signed out. |
| `mint` | Required backend callback returning a fresh token and matching nonce. |
| `onAction` | Optional app action handler; return true only when handled. |
| `onClose` | Optional host dismissal callback; leave absent when disabled. |
| `onReplaced` | Optional callback retaining the replacement WebView in identity-only renderer recovery. |

Enable JavaScript and use `adjustResize`. Keep navigation on allowed chat origins; open safe external URLs in the system browser. For a microphone-enabled view, recreate the Activity after renderer death so its ActivityResult launcher is registered before STARTED. Do not reinstall the microphone adapter from the late `onReplaced` callback. Dispose WebView listeners and the view during host teardown. The example shows both recovery paths.

Call `BusymateBridge.accountChanged()` after login, logout, session/account changes. Foreground resume is observed by the SDK. Your backend must sign the supplied nonce, with ES256, unique `jti` and expiry within 120 seconds. Never embed signing keys, cache launch tokens or log tokens. See [backend signing](https://busymate.ai/ru/docs/guides/identity-backend-signing) and the [complete configuration reference](https://github.com/serebano/busymate-ai-sdk-android/blob/1.0.0/docs/configuration.md).

## 4. Wire the OS microphone callback

Declare `android.permission.INTERNET` and `android.permission.RECORD_AUDIO` in AndroidManifest.xml. Construct `BusymateMicrophone(activity, webView, origins)` during `ComponentActivity.onCreate`, before STARTED and before loading chat. Forward `WebChromeClient.onPermissionRequest` on the UI thread to `allowMedia(request)`. The microphone transport requires WebView message-listener support; it has no JavascriptInterface fallback.

A mic or voice tap sends `busymate.microphone.v1.request` with `id` and `source`. The SDK obtains OS permission and returns `{ id, granted }`. Chat waits before capture or voice token minting. Denial and timeout fail closed; cancellation prevents a delayed grant from starting a cancelled session. OS permission remains controlled by the device. After changing permission in Settings, retry explicitly. See [microphone lifecycle and troubleshooting](https://github.com/serebano/busymate-ai-sdk-android/blob/1.0.0/docs/microphone.md).

## 5. Build and test the demo

Follow the [example-app build instructions](https://github.com/serebano/busymate-ai-sdk-android/blob/1.0.0/example-app/README.md). Use its Settings screen to change assistant, chat URL, exact origins, backend endpoint, account and microphone/action controls. Guest chat needs no fake identity; authenticated tests use your own backend. The event log supports integration troubleshooting without exposing credentials.

Knowledge, tools, handoff, branding and voice availability are workspace features. Locale and appearance follow supported hosted chat settings. The SDK does not invent native flags for these services or configure your host's audio routing.

## Verify

1. Build the demo and verify guest chat.
2. Use your backend to test sign-in, logout and account switching without history leakage.
3. On a physical device test first mic/voice grant, denial, Settings retry and cancellation while the prompt is open.
4. Test external links, close/action controls, background/resume and renderer recovery.

<!-- qa:start -->
### Where is the full API reference?
The versioned repository's configuration, identity and microphone guides describe all public SDK settings and lifecycle callbacks.

### Does the demo authenticate without my backend?
No. Guest mode works when enabled; authenticated mode requires your real backend and current session.

### Which updates require an app release?
SDK changes, OS permissions and native capabilities require an app release. Hosted chat changes arrive from the service.
<!-- qa:end -->