Using Eva's iOS SDK

This Blog post will describe how to install and use Eva SDK for iOS.

Project Setup and Installation

Download & Install the SDK

1. Download the SDK:
   git clone https://github.com/evature/ios/
   
   or download the file:  https://github.com/evature/ios/archive/master.zip
2. Make sure you are using the latest version of Xcode and targeting iOS6.0 or higher.
3. Drag Eva.framework folder to your Xcode project folder target (Make sure the “Copy items to destination’s group folder is checked).
   
   
   
   
4.  Click on the Targets -> Your app name -> and then “build phases” tab, and then expand “Link binary with libraries”
5. Add the following libraries:
        CoreLocation.framework
        AVFoundation.framework
   
   

Code Integration

UI Views Integration

1. Go to your “AppDelegate.m” file, and add this line:

#import <Eva/Eva.h>

And add the following lines to  didFinishLaunchingWithOptions:

-(BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions{
     [[Eva sharedInstance] setAPIkey:@"YOUR-API-KEY" withSiteCode:@"YOUR-SITE-CODE"];
}

2. Go to “YourViewController.h” (Where you want to integrate Eva) and import Eva also:

#import <Eva/Eva.h>

Add EvaDelegate to the Controller delegates, File should look like that:

#import <Eva/Eva.h>
@interface YourViewController : UIViewController < EvaDelegate>{
}
@end

3. Now, set the delegate in viewWillAppear:

-(void)viewWillAppear:(BOOL)animated{
    [Eva sharedInstance].delegate = self; // Setting the delegate to this view //
    // The delegate initiation is here for it to be set-up every time this view is called //
}

Do steps 2 to 3 to every view you want to integrate Eva.

Using Eva and Handling the Results

1. Implement the two delegates (a must):

#pragma mark - Eva Delegate
- (void)evaDidReceiveData:(NSData *)dataFromServer{
     NSString* dataStr = [[NSString alloc] initWithData:dataFromServer encoding:NSASCIIStringEncoding];
 
    NSLog(@"Received data from Eva %@", dataStr);
}

- (void)evaDidFailWithError:(NSError *)error{
    NSLog(@"Got error from Eva");
}

2. To start recording a new session call:

[[Eva sharedInstance] startRecord:TRUE];

If you want to continue the previous session should you call:

[[Eva sharedInstance] startRecord:FALSE];

This would keep the previous session number.

3.  When you want to stop the record, please call:

[[Eva sharedInstance] stopRecord];

Record would stop automatically, eg when silent is detected.

Expect to get a delegate call just after that.

4.  Instead of quering Eva using a recording, you can send text to Eva. Do so using

- (BOOL)queryWithText:(NSString *)text startNewSession:(BOOL)newSession 

5.  All configurable parameters are optional. Those can be set, For example:

[[Eva sharedInstance] setHome:@"paris"];
[[Eva sharedInstance] setVersion: @"v1.0"];

(it is recommended to do all those settings in the AppDelegate.m file just before the setApiKey:withSiteCode function )

6.  You can add additional properties to the Eva request using Eva’s optional_- those will not be used but will be recorded in Eva’s logs. This can be useful for debugging. For example:

[Eva sharedInstance].optional_dictionary = @{@“app_version" : @“2"}; 

Playing Audio Files

Eva SDK supports playing audio files before and/or after the recording. 

To enable sounds you should call one of the four methods below:

1. -(BOOL)setStartRecordAudioFile:(NSURL *)filePath

   The file passed will play when StartRecord is called.

2. -(BOOL)setRequestedEndRecordAudioFile:(NSURL *)filePath

   This file will play when stopRecord is called.

3. -(BOOL)setVADEndRecordAudioFile:(NSURL *)filePath

   This file will play when VAD (Voice Activity Detection) decides the recording  has ended.

4. -(BOOL)setCanceledRecordAudioFile:(NSURL *)filePath

      This file will play when cancelRecord is called.

Setting audio files is optional - the default is to have no sounds activated. You should call these function only once when the application loads. To disable sounds you can call the functions with the filePath parameter set to NULL.

These functions will return FALSE in case of error (eg. file not found, wrong file format, etc…). The error description will appear in the log. 

IMPORTANT:
Eva does not setup the AVAudioSession parameters for you.
If, for example, you wish the audio files to play using the device speaker and not the ear-piece you should run the following snippet (only once, when the application loads).

Setting AudioSession

NSLog(@"Setting Audio Session");
AVAudioSession *session = [AVAudioSession sharedInstance];
NSError *error;
[session setCategory:AVAudioSessionCategoryPlayAndRecord withOptions:AVAudioSessionCategoryOptionDefaultToSpeaker error:&error];
if (error != nil) {
     NSLog(@"Failed to setCategory %@", error);
}
[session setActive:YES error:&error];
if (error != nil) {
     NSLog(@"Failed setActive %@", error);
}

Advanced API Parameters

1. If you want to implement mic activity level inside your app, On either the Single View Project section or Multiple Views Project section, you should call:

[[Eva sharedInstance] setAPIkey:@"YOUR-API_KEY" withSiteCode:@"YOUR-SITE-CODE" withMicLevel:TRUE];

Instead of:

[[Eva sharedInstance] setAPIkey:@"YOUR-API_KEY" withSiteCode:@"YOUR-SITE-CODE"]; 

2. In case you set withMicLevel to TRUE you must implement:

-(void)evaMicLevelCallbackAverage: (float)averagePower andPeak: (float)peakPower;
-(void)evaMicStopRecording;

averagePower and peakPower are in decibels, evaMicLevelCallbackAverage:andPeak would be called for each mic buffer of samples. Check out EvaTest project for animation example.


3. It is recommended to know that Eva finished all setup before starting using it:

- (void)evaRecorderIsReady;

   
Called when initiation process is complete after setting the API keys.

4. In case you want to change default timeout for recording you can use:

[[Eva sharedInstance] setAPIkey:apiKeyString withSiteCode:siteCodeString withMicLevel:TRUE withRecordingTimeout:8.0f]; 

This is exactly same as on paragraph 1, but you can change 8 sec timeout to any value you wish in seconds, Pay attention to send a float value.


DEMO PROJECT

The SDK comes with a demo project called EvaTest.
While its not the prettiest app there is, it shows how easy it is to integrate with Eva.

The interesting parts are in MainViewController.m  -

1. initialization of Eva API keys, sounds files and AudioSession in viewDidLoad
2. evaMicLevelCallbackAverage - used to animate a progress bar.
3. evaDidReceiveData - minimal parsing of the json response.
4. The difference between continuing a session and starting a new one in the respective button handlers.
5. The difference between stop and cancel recording in the respective button handlers.