Getting started

The Ada Android SDK is a Kotlin library that you can use to embed your Ada AI Agent into your native Android application.

It also supports actions and settings that you can use to customize the behavior of your AI Agent. For example, you might want to set the language, or pass metadata. The Android SDK reference covers these options and more.

Compatibility

The published artifact is compiled with Kotlin 2.2.20 metadata. If your app is pinned to an older Kotlin compiler, upgrade that toolchain before integrating the SDK.

Install the Android SDK

Install the SDK from Maven Central. Add the dependency to your app-level build.gradle file:

1
dependencies {
2
    implementation "cx.ada:messaging-android:<version>"
3
}

Replace <version> with the latest version on Maven Central.

You only need this one artifact. It contains the embedded view, the full-screen activity, and the dialog. Older install guides that mention multiple Ada Android artifacts do not apply to this SDK.

1
repositories {
2
    mavenCentral()
3
}

After adding the dependency, synchronize your project.

Launch Ada

The SDK provides three integration surfaces. All three ship in the same artifact.

XML

The simplest way to start is via XML. Replace my-handle with the handle for your AI Agent.

1
<cx.ada.messaging.widget.AdaMessagingView
2
    android:id="@+id/ada_view"
3
    android:layout_width="match_parent"
4
    android:layout_height="match_parent"
5
    app:ada_handle="my-handle"
6
    app:ada_language="en" />

The ada_handle attribute is required to display the view. If you specify it as an attribute, the conversation loads when the view attaches to its parent. If you don’t specify it, initialize the view later with initialize(settings: AdaMessagingView.Settings):

1
val adaView = findViewById<AdaMessagingView>(R.id.ada_view)
2
3
val settings = AdaMessagingView.Settings.Builder("my-handle")
4
    .build()
5
adaView.initialize(settings)

Programmatically

To create the view in code, pass a context to the constructor, then initialize it with a settings object:

1
import cx.ada.messaging.widget.AdaMessagingView
2
3
val adaView = AdaMessagingView(context)
4
5
val settings = AdaMessagingView.Settings.Builder("my-handle")
6
    .language("en")
7
    .metaFields(
8
        AdaMessagingView.MetaFields.Builder()
9
            .setField("plan", "pro")
10
            .setField("signedIn", true),
11
    )
12
    .build()
13
adaView.initialize(settings)

Finally, add the view to your container to display it.

Activity

Use AdaMessagingActivity to open the conversation in a separate, full-screen window. Create an Intent, put the settings in it with the key AdaMessagingActivity.EXTRA_SETTINGS, then start the activity:

1
import android.content.Intent
2
import cx.ada.messaging.ui.AdaMessagingActivity
3
import cx.ada.messaging.widget.AdaMessagingView
4
5
val settings = AdaMessagingView.Settings.Builder("my-handle")
6
    .build()
7
8
startActivity(
9
    Intent(context, AdaMessagingActivity::class.java)
10
        .putExtra(AdaMessagingActivity.EXTRA_SETTINGS, settings),
11
)

You can subclass AdaMessagingActivity like a regular Android activity. Call getAdaView() from your subclass to access the underlying AdaMessagingView.

Dialog

Use AdaMessagingDialog to display the conversation on top of the current window. Pass the settings through the fragment arguments with the key AdaMessagingDialog.ARGUMENT_SETTINGS:

1
import cx.ada.messaging.ui.AdaMessagingDialog
2
3
val dialog = AdaMessagingDialog()
4
dialog.arguments = Bundle().apply {
5
    putParcelable(AdaMessagingDialog.ARGUMENT_SETTINGS, settings)
6
}
7
dialog.show(supportFragmentManager, AdaMessagingDialog.TAG)

Choose a runtime

The SDK can load two web runtimes inside its WebView:

• Legacy preserves the behavior of Ada’s existing Chat SDK. This is the default, and it remains fully supported.
• Messaging is Ada’s next-generation runtime. Features such as headless mode, identityToken, and sendMessage require it.

Opt into the Messaging runtime explicitly:

1
import cx.ada.messaging.AdaWebSdk
2
3
val settings = AdaMessagingView.Settings.Builder("my-handle")
4
    .webSdk(AdaWebSdk.Messaging)
5
    .build()

If you do nothing, the SDK stays on the Legacy runtime. That keeps a package upgrade free of end-user-visible conversation changes.

Runtime commands

Once the view is initialized, you can interact with it at runtime:

1
adaView.setLanguage("fr")
2
3
adaView.setMetaFields(
4
    AdaMessagingView.MetaFields.Builder()
5
        .setField("plan", "pro"),
6
)
7
8
adaView.setSensitiveMetaFields(
9
    AdaMessagingView.MetaFields.Builder()
10
        .setField("authToken", "secure-session-token"),
11
)
12
13
adaView.setDeviceToken("fcm-device-token")
14
15
adaView.addEventCallback { event ->
16
    Log.d("Ada", "event=${event.eventName}")
17
}
18
19
adaView.reset()
20
adaView.deleteHistory()

See the Android SDK reference for the full list of actions.

File uploads

AdaMessagingActivity and AdaMessagingDialog handle file selection for you. If you embed AdaMessagingView directly and your conversation flows use file uploads, set filePickerCallback:

1
adaView.filePickerCallback = { callback ->
2
    // Launch your file picker, then call callback.onFileTaken(uri).
3
    callback.onFileTaken(selectedUri)
4
    true
5
}

Return true to tell the SDK that your app handles the picker flow. You can store the callback and invoke onFileTaken(uri) later, or pass null to cancel the request.

Upgrade from the existing Android SDK

If you are migrating from the existing Ada Android SDK, the lowest-risk path is:

1. Replace the old Ada Android dependencies with the single cx.ada:messaging-android artifact.
2. Rename imports and XML tags from the old support.ada.embed.* namespace to cx.ada.messaging.*.
3. Keep the runtime on the default Legacy path first.
4. Move to the Messaging runtime later, as a separate, deliberate step.

This gives you a package upgrade with no end-user-visible conversation change on day one.

Side-by-side mapping

Before / after: imports

1
// Before
2
import support.ada.embed.widget.AdaEmbedView
3
4
// After
5
import cx.ada.messaging.widget.AdaMessagingView

Before / after: XML tag

1
<!-- Before -->
2
<support.ada.embed.widget.AdaEmbedView ... />
3
4
<!-- After -->
5
<cx.ada.messaging.widget.AdaMessagingView ... />

Compatibility notes

• The old support.ada.embed.* classes do not compile against the new artifact. Import renames are required.
• greeting is the preferred setter and XML attribute name. The older plural forms greetings and app:ada_greetings are still accepted as compatibility aliases.
• Zero-argument reset() calls compile cleanly on both the view and the dialog.
• Settings.Builder.sensitiveMetaFields(...) is supported at initialization time, and setSensitiveMetaFields(...) remains available for runtime updates.
• Deprecated Map<String, String> overloads still exist for migration compatibility. Use MetaFields.Builder for all new code.

Release checklist

Before shipping your integration or migration to production:

• Verify your real production handle launches successfully
• Test the exact surface you ship (embedded view, activity, or dialog)
• Confirm your logging or analytics layer still receives SDK events
• Test push token registration if your app depends on it
• Test reset() and deleteHistory() if your app exposes those actions
• Test uploads and downloads if your AI Agent uses them
• Test app background and foreground transitions, and process recreation
• Verify your consumer build uses a Kotlin 2.2-compatible Android toolchain