Android SDK quick start

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

1. 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.
2. 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-level build.gradle file.

// build.gradle
dependencies {
    implementation fileTree(dir: 'libs', include: ['*.jar', '*.aar'])
}

3. 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

1. 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()
  }
}

2. 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.

3. Synchronize the Gradle project.

Launch Ada

After installing the Android SDK, there are a few ways to start Ada:

• XML
• Programmatically
• Dialog
• Activity

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.