> ## Documentation Index
> Fetch the complete documentation index at: https://www.voiceflow.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Add the Voiceflow widget to Android

> Embed Voiceflow’s text-chat widget in your Android app using a hosted HTTPS page and the supplied WebView example. Test identity, recovery and release.

## Overview

Embed Voiceflow’s text-chat widget in your Android app using a hosted HTTPS
page and the supplied `WebView` Activity. This guide covers public support;
your app owns navigation and the screen’s lifetime.

**Note:** 

**Building your own interface?** Custom chat and voice walkthroughs are [coming soon](#custom-interface). Start with [Chat agents](/docs/api-reference/agent-runtime/chat) or [Voice agents](/docs/api-reference/agent-runtime/voice) for the APIs.

<a id="prepare"></a>

## Before you begin

Prepare the agent, hosted widget page and Android project.

Start with an existing agent; see [Build](/docs/documentation/build/overview) if you need to create one first.

| Requirement | What you need |
| --- | --- |
| Agent | Public widget access and an intended [Published release](/docs/documentation/deploy/environments/publishing). |
| Widget configuration | The [project ID](/docs/cookbook/find-your-project) and Environment alias from the project owner. |
| Website | An HTTPS host you control for the widget page. |
| Android project | The downloadable Activity requires API 26 or later. Retain your app’s current target SDK and dependencies. |
| Test and conversation policy | A known question and expected answer, any customer notice, and an agreed [retention/account-change policy](/docs/guides/channels/mobile/separate-app-conversations). |

The hosted page uses public widget identifiers. Keep private project API keys and app sign-in credentials on your backend.

<a id="host-page"></a>

## Host the widget page

Load the widget from an HTTPS origin you control.

The downloadable page uses public widget access with `verify.projectID`. Voice
controls are disabled; microphone access and file pickers need additional app work.

### 1. Configure the hosted page

Save [chat.html](/docs/examples/mobile/chat.html) in your web application. Set
`YOUR_PROJECT_ID` to the supplied project ID and `YOUR_ENVIRONMENT_ALIAS` to the
Environment alias.

The page passes your alias as `environmentID` and selects the published release
with `versionVariant: 'published'`. Keep its embedded rendering and session-only
storage; see [widget Environment routing](/docs/documentation/deploy/widget/web-chat-api#choosing-which-environment-the-widget-loads)
for options and compatibility.

### 2. Deploy and check the URL

Deploy to your HTTPS host, for example `https://support.example.com/chat.html`.
Have the project owner allow that origin if domain restrictions are enabled.
Your content security policy must allow the widget's CDN, styles and runtime
connections. Keep TLS checks enabled.

Open the final URL. The chat should replace the loading status. Use this same
URL in Android, then complete the [app conversation test](#test-conversation).
Use a hosted HTTPS page; local `file://` content has different origin/storage
behavior. See [Android's WebView guidance](https://developer.android.com/develop/ui/views/layout/webapps/webview).

<a id="install-view"></a>

## Add the Android widget screen

Configure the manifest and mount one WebView in the Help destination.

### 1. Register the Activity

Download the [example bundle](/docs/examples/mobile/mobile-examples.zip) and add
`SupportActivity.kt` to your app module. Replace `package com.example.app` with
your app package and set the hosted HTTPS URL. In `AndroidManifest.xml`, add
internet permission before `application` and the Activity inside it, retaining
your existing attributes:

```xml
<uses-permission android:name="android.permission.INTERNET" />

<!-- Inside the existing application element: -->
<activity
    android:name=".SupportActivity"
    android:exported="false"
    android:windowSoftInputMode="adjustResize" />
```

Keep cleartext traffic disabled. Open the Activity from your Help click handler:

```kotlin
startActivity(android.content.Intent(this, SupportActivity::class.java))
```

### 2. Keep the view configuration

Retain the example's settings for the trusted page:

- JavaScript and DOM storage enabled.
- File/content access disabled and mixed content blocked.
- HTTPS navigation restricted to the hosted origin, with no native bridge or SSL bypass.

Keep its padding for system bars, cutouts and keyboard insets, pause/resume
forwarding, and teardown on removal or renderer failure. Check your app's
[edge-to-edge layout](https://developer.android.com/develop/ui/views/layout/edge-to-edge).
Android documents [WebView setup](https://developer.android.com/develop/ui/views/layout/webapps/webview)
and [native bridge risks](https://developer.android.com/privacy-and-security/risks/insecure-webview-native-bridges).

### Use Jetpack Compose

Launch the Activity from Compose or adapt it to an inline WebView.

You can launch the same Activity from Help. For an inline view, use
[AndroidView](https://developer.android.com/develop/ui/compose/migrate/interoperability-apis/views-in-compose)
and create the WebView in its factory rather than on each recomposition. Retain
the same settings, lifecycle handling and cleanup, then test that adaptation in
your app.

<a id="identity-lifecycle"></a>

## Handle identity and app lifecycle

Keep widget conversations separate and handle app interruptions.

The widget creates a guest identity. `sessionStorage` retains state within the
surviving page session; Android WebView can also share web data across the app.

| App event | Required behavior |
| --- | --- |
| Background and resume | Forward pause/resume to a surviving WebView. Avoid reloading or sending another `launch` automatically. |
| Logout or account change | Destroy the old Help view and clear any persistent storage you add before loading another account. |
| Activity or app process recreated | This example starts fresh. Check rotation and process recreation. |
| View or connection fails | Destroy a failed renderer, then offer **Reload support**. |
| Explicit restart | Create a new view without automatically resending a message. |

A client-supplied `userID`, display name or launch value is not authenticated
identity. Revoke app/backend sessions separately on logout, and authorize
protected operations on every request. See [Separate app conversations](/docs/guides/channels/mobile/separate-app-conversations)
for the widget's account boundary. Keep account tokens out of the public page.

Android's [Activity lifecycle](https://developer.android.com/guide/components/activities/activity-lifecycle)
and [WebView process handling](https://developer.android.com/develop/ui/views/layout/webapps/managing-webview)
explain recreation behavior. Use [Recover interrupted conversations](/docs/guides/channels/mobile/recover-interrupted-conversations)
for safe recovery. WebView cleanup does not delete Voiceflow transcripts.

<a id="test-conversation"></a>

## Test an app conversation

Verify replies on an emulator and a physical device.

### 1. Open Help

Install the test build and open a fresh widget conversation. Accept any
configured notice. Check keyboard layout, Back navigation and readable replies.

### 2. Check a question and follow-up

Send the known support question, then a related follow-up. Confirm that the
intended agent answers visibly in the widget and the conversation continues correctly.

### 3. Interrupt and resume

Background and resume the app, then test network loss. Check rotation, Activity
recreation and renderer/process loss separately against the [lifecycle behavior](#identity-lifecycle).
Verify the expected retained or fresh conversation and check an uncertain
action's result before offering a retry.

### 4. Check account changes

Close and reopen Help to check retention. Sign out and switch accounts: the
previous conversation must be absent. If you added protected operations, confirm
stale backend requests are denied.

### 5. Check the released build

Repeat the question and follow-up in a fresh conversation on the distributed
build after publishing. Confirm that it uses the intended agent release and hosted page.

Record Android version, app build and WebView provider/version with failures.

### The widget does not load

Check JavaScript, DOM storage and the hosted origin first.

Confirm `javaScriptEnabled` and `domStorageEnabled`, resolved project/Environment
values and a non-empty embedded container. Inspect requests for public-access
rejection, approved-domain errors or blocked scripts/styles/runtime connections.
The origin must be your hosted HTTPS page, not `file://` or the Android package.

### The widget screen is blank or restarts

Distinguish navigation errors from Activity or renderer recreation.

Check HTTPS certificates, redirects and the allowed host/port. Do not bypass an
SSL error. Check whether your app created a new Activity/WebView, reloaded on
resume, or recreated the Activity after rotation. After renderer failure, remove
and destroy that instance; Android says it cannot be reused. The sample offers
an explicit reload that may start a fresh conversation.

### The wrong conversation or release appears

Check identity cleanup and routing independently.

Verify the project ID, Environment alias and Published release with a fresh
conversation. Check the hosted-page version. Review reused identities and retained state; clearing the
visible messages alone is insufficient. Check an uncertain action's result
before retrying.

<a id="release"></a>

## Release and maintain the app

Publish the agent, hosted widget page and Android build independently.

1. Publish the intended [agent and widget configuration](/docs/documentation/deploy/environments/publishing).
2. Deploy the hosted widget page with the verified configuration.
3. Distribute the Android build through your normal testing
and [Google Play release process](https://developer.android.com/studio/publish).
Repeat the [app conversation test](#test-conversation) in that build. Record the
agent, page and app versions independently; remote changes can affect
already installed apps.

### Update or roll back

Retain a working page and app build, then verify both fresh and returning use.

Roll back the layer responsible for the regression. An agent or page rollback does not replace native code or reset existing conversations. Retest a
fresh conversation and the intended return path. Record the observed widget bundle and WebView versions; both can change independently of your app.

### Remove the integration

Retire the app entry and its supporting services.

Remove the entry or distribute an app update. Keep the hosted page available until older supported builds no longer need it. Revoke
app-owned sessions and credentials according to your backend policy. Destroying
the view does not delete retained transcripts or constitute server-side logout.

<a id="custom-interface"></a>

## Custom interface guides

Planned Android guides for your own chat or voice UI.

Android walkthroughs for custom chat and voice interfaces are **coming soon**. These are separate from this widget guide.

| Planned guide | API reference |
| --- | --- |
| Add custom chat | [Chat agents](/docs/api-reference/agent-runtime/chat) |
| Add custom voice | [Voice agents](/docs/api-reference/agent-runtime/voice) |
