Getting started

This guide will help you set up the Ada Android SDK in your app. The process involves two main steps:

1. Install the SDK: Add the SDK manually to your project.
2. Launch Ada: Choose one of the available options to display Ada, such as XML, programmatic setup, dialog, or activity.

Follow the instructions below to install the SDK and start integrating Ada into your app!

Install Android SDK

1. Get the Android SDK .aar file here.

   To download the AAR file:

   • Click on the package you need (e.g., android-sdk, android-sdk-appcompat, or android-sdk-appcompat-legacy)
   • Select your desired version from the versions list
   • In the Files section, click on the .aar file to download it

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.

1
dependencies {
2
    implementation fileTree(dir: 'libs', include: ['*.jar', '*.aar'])
3
}

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.

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

1
implementation files("/path/to/android-sdk-<version_number>.aar")
2
implementation files("/path/to/android-sdk-appcompat-<version_number>.aar")

Install via Maven Central

Alternatively, you can install the Ada Android SDK directly from Maven Central Repository. Add the following dependency to your app-level build.gradle file:

Standard SDK

1
dependencies {
2
    implementation "io.github.adasupport:android-sdk:<version>"
3
    implementation "io.github.adasupport:android-sdk-appcompat:<version>"
4
}

Legacy SDK

For projects that require the legacy version:

1
dependencies {
2
    implementation "io.github.adasupport:android-sdk:<version>"
3
    implementation "io.github.adasupport:android-sdk-appcompat-legacy:<version>"
4
}

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

1
repositories {
2
    mavenCentral()
3
    // other repositories...
4
}

After adding the dependency, synchronize your project to download and integrate the SDK.

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

1
<!-- XML -->
2
<support.ada.embed.widget.AdaEmbedView
3
        android:id="@+id/ada_chat_frame"
4
        android:layout_width="match_parent"
5
        android:layout_height="match_parent"
6
        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).

1
// Delayed initialization
2
val adaView = findViewById(R.id.ada_chat_frame)
3
4
adaSettings = AdaEmbedView.Settings.Builder("ada-example")
5
    .build()
6
adaView.initialize(adaSettings)

Programmatically

To programmatically create the chat frame, create a view object and pass context to the constructor.

1
val adaView = AdaEmbedView(getContext())
2
3
val adaSettings = AdaEmbedView.Settings.Builder("ada-example")
4
    .build()
5
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.

1
val dialog = AdaEmbedDialog()
2
 adaDialog.arguments = Bundle().apply {
3
    putParcelable(AdaEmbedDialog.ARGUMENT_SETTINGS, settings)
4
 }

Then show it using the native Android show method.

1
dialog.show(supportFragmentManager, AdaEmbedDialog.TAG)

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.

1
val intent = Intent(context, AdaEmbedActivity::class.java)
2
intent.putExtra(AdaEmbedActivity.EXTRA_SETTINGS, settings)
3
context.startActivity(intent)

File Upload Support

If your implementation uses Zendesk live agent support, file uploads might require a few additional steps, based on your chosen method for launching the SDK.

AdaEmbedActivity and AdaEmbedDialog already have this functionality, but if you work directly with AdaEmbedView you must handle uploads as described below.

1. Set up a callback to AdaEmbedView. This callback will be fired when a user makes a request to attach a file.
2. Once you get the URI, invoke filePickerCallback.onFileTaken(someUri). This will signal to AdaEmbedView that the file is ready to attach. It’s also possible to pass null, which will cancel the request.

1
adaView.filePickerCallback = { filePickerCallback ->
2
    filePickerCallback.onFileTaken(someUri)
3
    true
4
}

This operation doesn’t require you to pass the file URI to callback immediately. You can save filePickerCallback and invoke the callback later (for example, taking the URI via file picker).

To notify AdaEmbedView that you are going to handle file attachments, you should return true.