Android Quick Start

Steps to getting your first Android app integrated with Slang

Before you start

You need to have the following software installed on your system:

• JDK version 8

• Android Studio version 4.0 or higher

• Android Platform API Level 16 or higher

Step 0: Setup

First off, open your Android app's project in Android Studio and prepare for Slang integration. For the remainder of this guide, we'll assume that the app is called MyAwesomeApplication.

Step 1: Add Slang library dependency

Open your project's module-level build.gradle file (Project Navigator -> Gradle Scripts -> build.gradle (Module: app).

Step 1a: Add the Slang repository:

allprojects {
  ...
  repositories {
    maven {
        url "http://maven.slanglabs.in:8080/artifactory/gradle-release"
    }
    ...
  }
}
// If your build fails due to failure to find slang_lib dependency, 
// try moving the path to Slang's maven repo to a position before jcenter.

Step 1b: Add the Slang library dependency

implementation('in.slanglabs.sdk.android:slang_lib:1.0.44')

Using auto-generated SlangInterface.java

At this point, if you have received a copy of SlangInterface.java with all of the initialization boilerplate generated for your app, you're very close to completing the integration. Just drop the file into your app's Android project and make sure to initialize the interface from within your app's Application class, like this:

public class MyAwesomeApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        SlangInterface.init(this);
    }
}

In SlangInterface.java, you will find empty methods like the following that represent actions that your app can perform:

   /**
     * Action for book_ride intent 
     */
    private static Status doBookRide(SlangSession slangSession, String address, String paymentMode) {
        Toast.makeText(sApplication, "Recognized book_ride intent").show();  // TODO: FIXME: implement it
        return Status.SUCCESS;
    }

You will need to replace the toast with the app logic necessary to complete the action for the appropriate intent. The Slang platform will ensure that the action is called automatically whenever a user speaks the corresponding utterance.

After implementing these action handlers, you can skip the following steps and directly jump to Step 5: Run the app.

Step 2: Gather credentials from Slang Console

If you haven't already configured your app's use cases in the Slang Console, please head to console.slanglabs.in and follow the steps in the Building Your First Buddy guide.

Once you've built a buddy corresponding to your app's use-cases, gather the API key and Buddy ID and have them handy for integration. For details on how to obtain these credentials from the Console, see here.

Step 3: Initialize Slang

To initialize Slang, you'll need to the applications Android context, the Buddy ID and API key gathered in Step 2. With these, you can initialize Slang in the following way:

import in.slanglabs.platform.SlangBuddy;
import in.slanglabs.platform.SlangBuddyOptions;
import in.slanglabs.platform.SlangLocale;

public class MyAwesomeApplication extends Application {
  @Override
  public void onCreate() {
    super.onCreate();
    
    // Configure options needed for Slang
    SlangBuddyOptions options = new SlangBuddyOptions.Builder()
        .setApplication(this)
        .setBuddyId("<Buddy_Id>")
        .setAPIKey("<API_Key>")        
        .setIntentAction(new MyIntentAction())
        .setRequestedLocales(getAppLocales())
        .setDefaultLocale(SlangLocale.LOCALE_ENGLISH_IN)
        .build();
    SlangBuddy.initialize(options);
  }
  
  // Return the required locales
  private Set<Locale> getAppLocales() {
    HashSet<Locale> locales = new HashSet<>(2);
    locales.add(SlangLocale.LOCALE_ENGLISH_IN);
    locales.add(SlangLocale.LOCALE_HINDI_IN);
    return locales;
  }
}

With these code changes, when the app is run, Slang will be initialized and a movable Trigger will be automatically inserted on each activity of the app as it's created. Users of the app will now be able to click on this trigger to initiate the voice experience and start talking. But, by default, no action will occur after the user finishes speaking. In order for actions to occur, we need to write action handlers.

Step 4: Write action handlers

As users talk, Slang attempts to understand what they're saying and take appropriate action. Every utterance of each user that is understood by Slang will result in an "Intent" being recognized and the appropriate action for the Intent being called.

To understand the details behind Intents, please see the section on Intents in Buddy Building Tips.

In your app, you can write action handlers that specify what actions need to be performed when Intents are recognized by Slang. Recall that we passed an instance of this action handler during initialization time in Step 3.

        .setIntentAction(new MyIntentAction())

Here is what an implementation of MyIntentAction could look like:

private static class MyIntentAction implements SlangIntentAction {
    @Override
    public Status action(SlangIntent intent, SlangSession session) {
        switch (intent.getName()) {
            case "roaming":
                // Handle roaming intent
                handleRoaming(intent);
                break;

            case "balance":
                // Handle balance intent
                handleBalance(intent);
                break;
            }

            // Inform Slang you handled this intent successfully
            return SUCCESS;
        }
    }
}

Step 4a: The "action" method

The "action" method of your SlangIntentAction implementation will be called every time an "Intent" is detected by Slang. This is where you can trigger functionality that exists in your app that corresponds to the detected intent/use-case. The logic can be as simple as launching an activity as shown here

private static class MyIntentHandler implements SlangIntentAction {
    @Override
    public Status action(SlangIntent intent, SlangSession session) {
        switch (intent.getName()) {
            case "balance":
                // Handle balance intent
                Intent i = new Intent(sAppContext, MainActivity.class);

                i.putExtra(
                    ActivityDetector.ACTIVITY_MODE,
                    ActivityDetector.MODE_BALANCE
                );

                sAppContext.startActivity(i);
                handleBalance(intent);
                break;
            }

            // Inform Slang you handled this intent successfully
            return SUCCESS;
        }
    }
}

Note that "Intents" being referred here are the intents/use-cases that were defined in the Slang Console. Not to be confused with the Android Intents!

Step 5: Run the app

Congratulations! That's all there is to integrating Slang with your app. Now, when you run your app, the trigger should appear automatically. Clicking on it and speaking an utterance configured for an app's use-case should perform the appropriate action.

Digging Deeper

While we've looked at a quick and easy way to get started with integrating Slang into your app, Slang provides many more features and options to control the overall voice experience for your app. To learn more about these features, options and APIs, please head to the Android Deep Dive section.