Alan Android SDK¶

Alan can be integrated with Android apps developed in Java and Kotlin.

Integrating with Alan¶

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

Step 1. 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
Download the aar package and include it manually

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: implementation 'app.alan:sdk:<latest-version>'. To get the latest version, check out the Releases page for the Alan Android SDK GitHub repository.

/// build.gradle file at the module level
...
dependencies {
  ...
  /// Add Alan SDK dependency
  implementation "app.alan:sdk:4.12.0"
}

aar package

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 the libs 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. To get the latest version, check out the Releases page for the Alan Android SDK GitHub repository.

/// 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-4.12.0', ext: 'aar')
}

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

<com.alan.alansdk.button.AlanButton
    android:id="@+id/alan_button"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:layout_gravity="bottom"
    android:visibility="visible"
    app:button_horizontal_align="right"
    app:layout_constraintBottom_toBottomOf="parent"
    app:layout_constraintEnd_toEndOf="parent"/>

Note

The layout_width param should be set to match_parent.

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

Java

/// MainActivity.java file
public class MainActivity extends AppCompatActivity {

  /// Add the alanButton variable
  private AlanButton alanButton;

  @Override
  protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);

    /// Set up the Alan button
    AlanConfig config = AlanConfig.builder().setProjectId("").build();
    alanButton = findViewById(R.id.alan_button);
    alanButton.initWithConfig(config);
  }
}

Kotlin

/// MainActivity.kt file
class MainActivity : AppCompatActivity() {

  /// Add the alanButton variable
  private var alanButton: AlanButton? = null

  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_main)

    /// Set up the Alan button
    val config = AlanConfig.builder().setProjectId("").build()
    alanButton = findViewById(R.id.alan_button)
    alanButton?.initWithConfig(config)
  }
}

Step 4. 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.

Java

/// MainActivity.java file
public class MainActivity extends AppCompatActivity {

  private AlanButton alanButton;

  @Override
  protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);

    /// Define the project key
    AlanConfig config = AlanConfig.builder().setProjectId("e40fc04e9aff7b4b7d43485dbc3cb44a2e956eca572e1d8b807a3e2338fdd0dc/stage").build();
    alanButton = findViewById(R.id.alan_button);
    alanButton.initWithConfig(config);
  }
}

Kotlin

/// MainActivity.kt file
class MainActivity : AppCompatActivity() {

  private var alanButton: AlanButton? = null

  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_main)

    /// Define the project key
    val config = AlanConfig.builder().setProjectId("e40fc04e9aff7b4b7d43485dbc3cb44a2e956eca572e1d8b807a3e2338fdd0dc/stage").build()
    alanButton = findViewById(R.id.alan_button)
    alanButton?.initWithConfig(config)
  }
}

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.

Handling 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:

Java

AlanCallback myCallback = new AlanCallback() {
  @Override
  public void onCommandReceived(EventCommand eventCommand) {
    super.onCommandReceived(eventCommand);
      //Handle command here
    }
  };
alanButton.registerCallback(myCallback);

Kotlin

val myCallback: AlanCallback = object : AlanCallback() {
  override fun onCommandReceived(eventCommand: EventCommand) {
    super.onCommandReceived(eventCommand)
    //Handle command here
  }
}
alan_button.registerCallback(myCallback)

Switching between logging levels¶

You can switch to the extended logging level with a static enableLogging method of the Alan object:

Alan.enableLogging(true);

Troubleshooting¶

The minimum possible Android SDK version required by the Alan SDK is 21. If the version in your project is lower, you may encounter the following error: AndroidManifest.xml Error: uses-sdk:minSdkVersion 16 cannot be smaller than version 21 declared in library [:alan_voice]. Open the app/build.gradle file, under defaultConfig, locate minSdkVersion and change the version to 21.