Using Eva's Android SDK

This post will describe how to integrate Eva in an Android Project.

SDK Structure

The SDK comes with three directories:

• EvaAPIs: The Eva SDK 
• android_demo:  A minimal demo that allows sending text to Eva and displays the response on the screen.
• android_search: A larger sample application which demonstrates Eva’s usage for searching for hotels. The application can search and book hotels using Expedia API. It has a Google map display, however to use it you must use your own API keys (Expedia, Google maps, Vayant).

Download or clone the SDK from:  https://github.com/evature/android

How to use the SDK

1. Import the EvaAPIs project to your Eclipse workspace as an existing Android Project.
2. Add EvaAPIs as a library to your own project -
1. Right click your project, choose “properties”. 
2. Click “Android” in the left side menu.
3. Add a reference to the EvaAPIs project.
3.  Add required permissions to your AndroidManifest:
   
   Required permissions:
       android.permission.INTERNET
       android.permission.ACCESS_FINE_LOCATION
       android.permission.ACCESS_COARSE_LOCATION
   
   If you want to use the voice based search you also need:
       android.permission.RECORD_AUDIO

At this point you can start using Evature SDK -

A minimal integration is very simple:

1. extend EvaBaseActivity
2. override the onEvaReply listener callback to handle Eva reply
3. call "searchWithText" or "searchWithVoice" methods to send user input to Eva.

Class Reference

EvaApiReply

Reply object for Eva, populated into java classes.

Documentation for it can be found  at:

http://www.evature.com/docs/response.html#api-reply-in-depth

EvaBaseActivity

Base activity for activities that use the Eva SDK. 

Note: 

Many Android frameworks and libraries require you to extend your main activity from a base class (eg. RoboGuice, ActionbarSherlock, more…) . This is problematic since Java does not allow multiple inheritance and so only one such library can be used. Eva SDK is compatible with such libraries - you can use Eva without extending the base class but it requires more “wiring” and isn’t recommended if not required. See the section below on using Eva without extending from a base class.  

public methods:

void speak(String sayIt, [boolean flush])

Uses TTS to say a string.  Eva will delay the speech until the TTS (Text to speech) engine is ready, so calling speak(“hello”)  in onCreate of the activity may be delayed by a few seconds.
If the flush parameter is true (defualt) then calling a second speak while a first is still playing will stop the first speech.   eg. use speak(“”) to stop the speech.

void searchWithVoice(Object cookie, boolean editLastUtterance)

Eva will start a recording of user. When silence is detected (after a period of non-silence) the recording is automatically stopped.
The user speech will be used as input text by Eva to generate the result.
It is essential to stop TTS before starting a recording - call speak(“”)
It is essential to let the user know he is being recorded -
We strongly recommend to play a short “beep” before starting the recording, and also show a visual mark that a recording is ongoing. If you add a visual mark you should override speechResultOK and speechResultError (see below) to disable the visual mark when the recording completes.
See “visual feedback of ongoing recording” below for optional visual feedback provided by Eva.

Parameters:

• editLastUtterance:  tell Eva the current input replaces the previous one. 

• cookie: The cookie parameter will be returned untouched with the search result callback, this can be used to store data known when the search is triggered and which useful when the result arrives. Pass null if not needed.

void searchWithText(String text  , Object cookie, boolean editLastUtterance)

Send a query to Eva with text instead of voice. The result will trigger a callback onEvaReply  (see below).
Parameters:

• text: Text to query for 

• cookie, editLastUtterance: see above.

void replyToDialog(int replyIndex, Object cookie)

When confronted with a multiple choice question in an Eva Reply, the answer chosen by the user should be sent using this function.

boolean isNewSession()

Returns true if the current state is of a new session.

void resetSession()

Start a new session.

void cancelSearch()

Stop an ongoing search - no callback will be activated.

Configuration:
The class includes different getters and setters for configuration of Eva - for example:

apiKey, siteCode - the credentials to use Eva.
locale -  see http://www.evature.com/docs/request.html#locale.
language - auto translated input_text and EvaReply, and also change the TTS language.
context - see http://www.evature.com/docs/request.html#scope

Method Overrides:

public void onEvaReply(EvaApiReply reply, Object cookie)  

Override this method to get the EvaReply from a voice or text search. Cookie is the object that was passed to the search request which triggered this reply.

public void newSessionStarted(boolean selfTriggered)

Called when a new session has started. If the parameter is true this is in response to a  resetSession call, otherwise it means Eva’s logic decided that the previous request started a new session.

speechResultOK

this method is called when a valid response is returned. The first parameter is the response string that can be passed to EvaApiReply constructor. 

speechResultError

called when there is an error (such as connection timeout) and the parameter is the error message. The default behaviour is to show the message in a Toast.

Advanced use cases

Using Eva without extending a base class

Many Android frameworks and libraries require you to extend your main activity from a base class (eg. RoboGuice, ActionbarSherlock, more…). This is problematic since Java does not allow multiple inheritance and so only one such library can be used. 

To overcome this problem you can use Eva without extending a base class. To do so follow the following steps:

Create a com.evaapis.EvaSearchReplyListener.

Create a field of type EvaComponent  - the constructor requires two parameters:  Activity and EvaSearchReplyListener.

In your activity’s onCreate, onResume, onPause, onActivityResult, onDestroy methods call the matching methods on the EvaComponent field.  

At this point you can use the methods described above for EvaBaseActivity - but activate them on the EvaComponent object or EvaSpeechComponent.

Visual feedback of ongoing recording

While the recording is ongoing, you can poll Eva for data such as current volume or even a buffer of the previous samples. This data can be visualized on the screen, for example brighter background color on higher volume. 

Data for visualization can be queried from the class SpeechAudioStreamer which can be retrieved from the EvaSpeechComponent using 

Polling the recorder state and updating GUI can be done using android.os.Handler class. 

For example:

updateLevel = new Handler()  {
   @Override
   public void handleMessage(Message msg) {
      SpeechAudioStreamer  speechAudioStreamer = speechSearch.getSpeechAudioStreamer();
      //   can read audio state from speechAudioStreamer here and update GUI based on it
      sendEmptyMessageDelayed(0, 50); // poll the statistics every 50ms
      super.handleMessage(msg);
   }
};
// send initial message to start the polling
updateLevel.sendEmptyMessageDelayed(0, 50);
// start the recording

Eva provides a widget to visualize the wave-form of the recording, the class SoundView. To update it run:

soundView.setSoundData(  speechAudioStreamer.getSoundLevelBuffer(),
                         speechAudioStreamer.getBufferIndex()
);