Alan Android SDK
Alan can be integrated with Android apps developed in Java and Kotlin. The integration procedure for Android Java/Kotlin apps is the same. To add Alan voice to an Android app, you need to do the following:
- Add the Alan SDK dependency
- Add the Alan button to the app layout
- Add the AlanConfig object
- Connect to the Alan Studio project
Add the Alan SDK dependency
You need to add the Alan SDK dependency to the Android app. You can do it in two ways:
Add a reference as a Maven dependency
Do the following:
- Open the
build.gradle
file at the module level. - In the
dependencies
block, add the dependency configuration for the Alan Android SDK, for example:implementation 'app.alan:sdk:4.7.15'
.
//build.gradle file at the module level
...
dependencies {
...
//Add Alan SDK dependency
implementation "app.alan:sdk:<latest.version>"
}
Download the aar package and include it manually
Do the following:
- Download the Alan SDK from the releases section in the Alan Git repository.
- Put it in your
<project>/app/libs
folder. Create thelibs
folder if needed. - Open the
build.gradle
file at the module level. - In the
repositories
block, add the name of the folder in which the aar package resides. - In the
dependencies
block, add the dependency configuration for the Alan Android SDK.
//build.gradle file at the module level
repositories {
...
//Add the following line to the repositories section
flatDir {
dirs 'libs'
}
}
...
dependencies {
...
//Add the Alan SDK dependency
implementation (name: 'AlanSdk-<version>', ext: 'aar')
}
Add the Alan button to the app layout
To add the Alan button to the layout of your app, use the AlanButton
class. The AlanButton
class provides a view with the voice button and instance methods to communicate with Alan Studio.
In activity_main.xml
, create a new AlanButton
instance using the following XML layout:
//activity_main.xml file
<com.alan.alansdk.button.AlanButton
app:layout_constraintBottom_toBottomOf="parent"
app:layout_constraintEnd_toEndOf="parent"
android:id="@+id/alan_button"
android:layout_width="match_parent"
android:layout_height="wrap_content"/>
The
layout_width
param should be set tomatch_parent
.
Add the AlanConfig object
You need to add the AlanConfig
object to your app. This object describes the parameters that are provided for AlanButton
. In the MainActivity.java
file (for Android Java apps) or the MainActivity.kt
file (for Android Kotlin apps), use AlanConfig.Builder
to create a config with the necessary parameters:
Name | Type | Description |
---|---|---|
projectId | String | Project key from Alan Studio |
dialogId | String | (Optional) Dialog ID to connect to the necessary dialog |
dataObject | String|JSONObject | (Optional) Valid JSON string or JSON object that must be passed to the Alan Studio project |
Connect to the Alan Studio project
As the last step, you need to connect the Android app to the Alan Studio project in which you create voice scripts for the app. In setProjectId
of MainActivity
, provide the Alan SDK Key for your project in Alan Studio. To get the key, in Alan Studio, at the top of the code editor click Integrations and copy the key value from the Alan SDK Key field.
Your app is now integrated with Alan. You can now add voice commands to the script in Alan Studio, run the app, tap the Alan button and interact with the app with voice.
Handle events from the Alan Android SDK
When you run an Android app with Alan voice, multiple callbacks come from the Alan backend. To handle them, you should extend the AlanCallback
class and register a listener to the AlanButton
object.
You can handle the following events:
-
onConnectStateChanged: This callback is invoked when the state of the connection to the backend changes.
Callback definition:
/** * Invoked on backend connection state change * @param connectState */ public void onConnectStateChanged(@NonNull ConnectionState connectState) { }
-
onDialogStateChanged: This callback is invoked when the Alan button interaction state changes.
Callback definition:
/** * Invoked on button interaction state change * @param dialogState */ public void onDialogStateChanged(@NonNull DialogState dialogState) { }
-
onRecognizedEvent: This callback is invoked when the user utterance is recognized at the backend.
Callback definition:
/** * Invoked when user speech is recognized at backend * @param eventRecognised */ public void onRecognizedEvent(EventRecognised eventRecognised) { }
-
onCommandReceived: This callback is invoked when the app receives a command from the voice script.
Callback definition:
/** * Invoked when some command from the voice script is received * @param eventCommand */ public void onCommandReceived(EventCommand eventCommand) { }
-
onTextEvent: This callback is invoked when an answer from the script is received.
Callback definition:
/** * Invoked on answer from the script * @param eventText */ public void onTextEvent(EventText eventText) { }
-
onEvent: This callback is invoked on any other Alan event.
Callback definition:
/** * Invoked on any other event * @param event * @param payload */ public void onEvent(String event, String payload) { }
-
onError: This callback is invoked on an Alan error event.
Callback definition:
/** * Invoked on Alan errors */ public void onError(String error) { }
The example below demonstrates how to handle commands coming from the voice script to the app: