The Ada Android SDK is a small framework that you can use to embed your Ada chatbot into your native Android application.
It also supports actions and settings that you can use to customize the behavior of your bot. For example, you might want to set the bot language, or customize the greeting. The Android SDK reference covers these options and more.
Quick start for Android
You can install the Ada Android SDK manually or using Gradle. The SDK supports Android 9 (Pie) and up.
Install Android SDK manually
- Get the Android SDK
.aar
file here or from Maven Central. Note that you can only download version 1.8.0 and up from these links. - To install the library, save the
.aar
file under your app module libs folder (for example "MyAwesomeProject/app/libs"), and include*.aar
in the application-levelbuild.gradle
file.
// build.gradle
dependencies {
implementation fileTree(dir: 'libs', include: ['*.jar', '*.aar'])
}
- Synchronize the project.
You can also import an .aar
file using Android Studio. First, download the versioned .aar
, and then simply define the implementation for the new local library module.
// build.gradle
implementation files("/path/to/android-sdk-<version_number>.aar")
Note that if the android-sdk-appcompat-<version_number>.aar
or the android-sdk-appcompat-legacy-<version_number>.aar
is used, then the dependency declaration must resemble the following, with the appcompat
libraries depending on the android-sdk
library.
// build.gradle
implementation files("/path/to/android-sdk-<version_number>.aar")
implementation files("/path/to/android-sdk-appcompat-<version_number>.aar")
Install Android SDK using Gradle
- To integrate the SDK, add the following code to the project-level
build.gradle
file. This ensures that your application can pull the Android SDK from the Maven Central repository.
// build.gradle
allprojects {
repositories {
mavenCentral()
}
}
- Get the latest Ada Android SDK package from the Ada Support Maven Repository. Note that you can only download version 1.8.0 and up using this resource identifier.
dependencies {
implementation 'io.github.adasupport:android-sdk:<version_number>
}
Choose android-sdk
unless one of the following is true:
- If your project has artifacts within the AndroidX namespace, use
implementation 'io.github.adasupport.android-sdk-appcompat:<version_number>'
. - If your project uses Android Support Library, use
implementation 'io.github.adasupport:android-sdk-appcompat-legacy:<version_number>'
.
The appcompat
packages allow you to use newer Android API features on older devices. Unlike when using .aar
files directly, only one implementation declaration is needed in the dependencies
block. The appcompat
packages will automatically resolve the dependency on the android-sdk
library.
- Synchronize the Gradle project.
Launch Ada
After installing the Android SDK, there are a few ways to start Ada:
XML
The simplest way to start Ada chat is via XML, as in the following example. You must replace my-bot
with the actual name of your bot, and modify any other relevant as needed.
<!-- XML -->
<support.ada.embed.widget.AdaEmbedView
android:id="@+id/ada_chat_frame"
android:layout_width="match_parent"
android:layout_height="match_parent"
app:ada_handle="my-bot" />
To display the view, the ada_handle
parameter is required. If you specify it as an attribute, the chat is displayed immediately upon attachment to the parent view. If it is not specified, then you can do it later programmatically, using the method initialize(settings: AdaEmbedView.Settings)
.
// Delayed initialization
val adaView = findViewById(R.id.ada_chat_frame)
adaSettings = AdaEmbedView.Settings.Builder("ada-example")
.build()
adaView.initialize(adaSettings)
Programmatically
To programmatically create the chat frame, create a view object and pass context to the constructor.
val adaView = AdaEmbedView(getContext())
val adaSettings = AdaEmbedView.Settings.Builder("ada-example")
.build()
adaView.initialize(adaSettings)
After this, the view will be created, but will not be initialized. To do this, call initialize(settings: AdaEmbedView.Settings)
, passing the settings object as an argument.
Finally, to display the newly created chat frame on screen, simply add the view to your container.
Dialog
To display a separate chat window on top of the current window, you can use AdaEmbedDialog
.
First, create a dialog object and pass the settings to its arguments using a constant, AdaEmbedDialog.ARGUMENT_SETTINGS
.
val dialog = AdaEmbedDialog()
adaDialog.arguments = Bundle().apply {
putParcelable(AdaEmbedDialog.ARGUMENT_SETTINGS, settings)
}
Then show it using the native Android show
method.
dialog.show(supportFragmentManager, AdaEmbedDialog.TAG)
TAG is a simple class name, you can use any value you want.
Activity
Use AdaEmbedActivity
to open the chat in a separate window attached to the app navigation.
To do this, create an Intent
, and put the settings in it with the key AdaEmbedActivity.EXTRA_SETTINGS
, then run the activity.
val intent = Intent(context, AdaEmbedActivity::class.java)
intent.putExtra(AdaEmbedActivity.EXTRA_SETTINGS, settings)
context.startActivity(intent)
You can use "AdaEmbedActivity" as a regular Android activity. For example, flags and actions can be added.