Alan iOS SDK

Alan can be integrated with iOS apps developed in both Swift and Objective-C. The integration procedure for iOS Swift/Objective-C apps is the same. To add Alan voice to an iOS app, you need to do the following:

Set up an XCode project
Integrate with Swift or Objective-C
Add the AlanConfig object
Add the Alan button

Set up an XСode project

You need to set up an XCode project to be used with Alan. You can do it in two ways:

Set up an XCode project with CocoaPods
Set up an XCode project manually

Set up an XCode project with CocoaPods

Do the following:

Install CocoaPods:
```
sudo gem install cocoapods
```
Go to the project folder and create a Podfile for the project:
```
pod init
```

Open and edit the Podfile:

use_frameworks!
platform :ios, '11.0'
target '<Your Target Name>' do
pod 'AlanSDK-iOS'
end

In the project folder, install the dependencies for the project:
```
pod install
pod update
```
Open the generated XCode workspace.
Go to the Info tab. Add the NSMicrophoneUsageDescription key to Info.plist of the application. It must be added to get the microphone access.
To allow the background mode in an iOS application, go to the Signing & Capabilities tab and select Audio, AirPlay, and Picture in Picture. The background mode must also be turned on in the Alan Studio project (Embed Code section).
Go to the Build phases tab. Click the + button, select New Run Script Phase and add the following:
```
sh "${SRCROOT}/Pods/AlanSDK-iOS/AlanSDK-iOS/Frameworks/AlanSDK.framework/frameworks-strip.sh"
```
Why is this script needed? The frameworks are not just single executables. They are actually FAT binaries that are archives of linked executables on different architectures. This includes architecture slices for arm64 and armv7 that are necessary for deployment on the phone, as well as i386 and x86_64 that are necessary for running the app in the simulator. The frameworks-strip.sh script main responsibility is to take care of removing unnecessary slices. This reduces the final package size.

Set up an XCode project manually

Do the following:

Open the Alan iOS SDK release page on GitHub.
Download the AlanSDK.framework.zip file from the recent release.
Extract AlanSDK.framework from the zip archive.
Drag and drop AlanSDK.framework to the XCode project.
Select the Copy items if needed check box if it is not selected.
Select the XCode project file and go to the General tab. Under the Frameworks, Libraries, and Embedded Content section, find AlanSDK.framework and select Embed & Sign from the list.
Go to the Info tab. Add the NSMicrophoneUsageDescription key to Info.plist of the application. It must be added to get the microphone access.
To allow the background mode in an iOS application, go to the Signing & Capabilities tab and select Audio, AirPlay, and Picture in Picture. The background mode must also be turn on in the Alan Studio project (Embed Code section).
Go to the Build phases tab. Click the + button, select New Run Script Phase and add the following:
```
sh "${BUILT_PRODUCTS_DIR}/${FRAMEWORKS_FOLDER_PATH}/AlanSDK.framework/frameworks-strip.sh"
```
Why is this script needed? The frameworks are not just single executables. They are actually FAT binaries that are archives of linked executables on different architectures. This includes architecture slices for arm64 and armv7 that are necessary for deployment on the phone, as well as i386 and x86_64 that are necessary for running the app in the simulator. The frameworks-strip.sh script main responsibility is to take care of removing unnecessary slices. This reduces the final package size.

Integrate with Swift

You need to add the following Swift snippet to your view controller:

Import AlanSDK:
```
import AlanSDK
```
Define the AlanButton variable:
```
fileprivate var button: AlanButton!
```

Set up AlanButton in viewDidLoad():

let config = AlanConfig(key: "YOUR_KEY_FROM_ALAN_STUDIO_HERE")
self.button = AlanButton(config: config)
self.button.translatesAutoresizingMaskIntoConstraints = false
self.view.addSubview(self.button)
let b = NSLayoutConstraint(item: self.button, attribute: .bottom, relatedBy: .equal, toItem: self.view, attribute: .bottom, multiplier: 1, constant: -40)
let r = NSLayoutConstraint(item: self.button, attribute: .right, relatedBy: .equal, toItem: self.view, attribute: .right, multiplier: 1, constant: -20)
let w = NSLayoutConstraint(item: self.button, attribute: .width, relatedBy: .equal, toItem: nil, attribute: .notAnAttribute, multiplier: 1.0, constant: 64)
let h = NSLayoutConstraint(item: self.button, attribute: .height, relatedBy: .equal, toItem: nil, attribute: .notAnAttribute, multiplier: 1.0, constant: 64)
self.view.addConstraints([b, r, w, h])

Run the application and tap the Alan button:

Integrate with Objective-C

Add this Objective-C snippet to your view controller.

Import AlanSDK:
```
@import AlanSDK;
```

Define the AlanButton variable:

@property (nonatomic) AlanButton* button;

Set up AlanButton in viewDidLoad:

AlanConfig* config = [[AlanConfig alloc] initWithKey:@"YOUR_KEY_FROM_ALAN_STUDIO_HERE"];
self.button = [[AlanButton alloc] initWithConfig:config];
[self.button setTranslatesAutoresizingMaskIntoConstraints:NO];
[self.view addSubview:self.button];
NSLayoutConstraint* b = [NSLayoutConstraint constraintWithItem:self.button attribute:NSLayoutAttributeBottom relatedBy:NSLayoutRelationEqual toItem:self.view attribute:NSLayoutAttributeBottom multiplier:1 constant:-40.0];
NSLayoutConstraint* r = [NSLayoutConstraint constraintWithItem:self.button attribute:NSLayoutAttributeRight relatedBy:NSLayoutRelationEqual toItem:self.view attribute:NSLayoutAttributeRight multiplier:1 constant:-20];
NSLayoutConstraint* w = [NSLayoutConstraint constraintWithItem:self.button attribute:NSLayoutAttributeWidth relatedBy:NSLayoutRelationEqual toItem:nil attribute:NSLayoutAttributeNotAnAttribute multiplier:1 constant:64.0];
NSLayoutConstraint* h = [NSLayoutConstraint constraintWithItem:self.button attribute:NSLayoutAttributeHeight relatedBy:NSLayoutRelationEqual toItem:nil attribute:NSLayoutAttributeNotAnAttribute multiplier:1 constant:64.0];
[self.view addConstraints:@[b, r, w, h]];

Run the application and tap the Alan button:

Add the AlanConfig object

You need to add the AlanConfig object to your app. This object describes the parameters that are provided for AlanButton.

Create a new AlanConfig instance with your Alan project SDK key:
```
- (instancetype)initWithKey:(NSString *)key;
```
Name Type Description

key NSString Project key from the Alan Studio
Create a new AlanConfig instance with your Alan project SDK key and custom data object:
```
- (instancetype)initWithKey:(NSString *)key dataObject:(NSDictionary *)dataObject;
```
Name Type Description

key NSString Project key from the Alan Studio

dataObject NSDictionary Given data object which will be passed to the Alan Studio project

For example:
```
AlanConfig *config = [[AlanConfig alloc] initWithKey:@"YOUR_KEY_FROM_ALAN_STUDIO_HERE"];
```

Name	Type	Description
`key`	NSString	Project key from the Alan Studio

Name	Type	Description
`key`	NSString	Project key from the Alan Studio
`dataObject`	NSDictionary	Given data object which will be passed to the Alan Studio project

Add the Alan button

To add the Alan button to your app, use the AlanButton class. This class provides a view with the voice button and instance methods to communicate with the Alan Studio.

Сreate a new AlanButton instance with the config object:

- (instancetype)initWithConfig:(AlanConfig *)config;

Name	Type	Description
`config`	AlanConfig	AlanConfig object for configuration which is described above

For example:

@interface ViewController ()
@property (nonatomic) AlanButton *button;
@end

@implementation ViewController
- (void)viewDidLoad
{
    [super viewDidLoad];
    AlanConfig *config = [[AlanConfig alloc] initWithKey:@"YOUR_KEY_FROM_ALAN_STUDIO_HERE"];
    self.button = [[AlanButton alloc] initWithConfig:config];
    [self.button setTranslatesAutoresizingMaskIntoConstraints:NO];
    [self.view addSubview:self.button];

    NSLayoutConstraint *right = [NSLayoutConstraint constraintWithItem:self.button attribute:NSLayoutAttributeRight relatedBy:NSLayoutRelationEqual toItem:self.view attribute:NSLayoutAttributeRight multiplier:1 constant:-20.0];
    NSLayoutConstraint *bottom = [NSLayoutConstraint constraintWithItem:self.button attribute:NSLayoutAttributeBottom relatedBy:NSLayoutRelationEqual toItem:self.view attribute:NSLayoutAttributeBottom multiplier:1 constant:-20.0];
    NSLayoutConstraint *width = [NSLayoutConstraint constraintWithItem:self.button attribute:NSLayoutAttributeWidth relatedBy:NSLayoutRelationEqual toItem:nil attribute:NSLayoutAttributeNotAnAttribute multiplier:1 constant:64.0];
    NSLayoutConstraint *height = [NSLayoutConstraint constraintWithItem:self.button attribute:NSLayoutAttributeHeight relatedBy:NSLayoutRelationEqual toItem:nil attribute:NSLayoutAttributeNotAnAttribute multiplier:1 constant:64.0];
    [self.view addConstraints:@[right, bottom, width, height]];
}
@end

You can use the Alan button methods to do the following:

Play text via Alan
Send a voice synchronized data event
Set a visual state of the app
Call a function from the voice script

Playing text via Alan

- (void)playText:(NSString *)text;

Name	Type	Description
`textString`	NSString	Text to be played

For example:

- (IBAction)didTapPlayButton:(id)sender
{
    NSString *play = @"someString";
    [self.button playText:play];
}

Sending a voice synchronized data event

- (void)playCommand:(NSDictionary *)command;

Name	Type	Description
`command`	NSDictionary	Data event to be sent

For example:

- (IBAction)didTapDataButton:(id)sender
{
    NSDictionary *data = @{@"someKey": @"someValue"};
    [self.button playCommand: data];
}

Setting a visual state of the app

- (void)setVisualState:(NSDictionary *)visualStateData;

Name	Type	Description
`data`	NSDictionary	Data with the visual state description

For example:

- (IBAction)didTapVisualButton:(id)sender
{
    NSDictionary *visual = @{@"someScreen": @"someValue"};
    [self.button setVisualState:visual];
}

Calling a function from the voice script

- (void)callProjectApi:(NSString *)method withData:(NSDictionary*)data callback:(void(^)(NSError *error, NSString *object))callback;

Name	Type	Description
`method`	NSString	Function name
`data`	NSDictionary	Function params
`callback`	(void(^)(NSError error, NSString object))	Callback to handle the result

For example:

- (IBAction)didTapCallButton:(id)sender
{
    NSString *function = @"script::updateGPS";
    NSDictionary *data = @{@"lat": @"55.0000", @"lon": @"55.0000"};
    [self.button callProjectApi:function withData:data callback:^(NSError *error, NSString *object) {
        NSLog(@"result: %@", object);
    }];
}

Handle events from the Alan iOS SDK

To handle events coming from the Alan iOS SDK, add an observer for a notification with the kAlanSDKEventNotification name. For example:

- (void)viewDidLoad
{
    [super viewDidLoad];
    [[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(handleEvent:) name:@"kAlanSDKEventNotification" object:nil];
}

- (void)handleEvent:(NSNotification*)notification
{
    NSDictionary *userInfo = notification.userInfo;
    if( userInfo == nil )
    {
        return;
    }
    NSString *jsonString = [userInfo objectForKey:@"jsonString"];
    if( jsonString == nil )
    {
        return;
    }
    NSData *jsonData = [jsonString dataUsingEncoding:NSUTF8StringEncoding];
    NSError *error = nil;
    id unwrapped = [NSJSONSerialization JSONObjectWithData:jsonData options:NSJSONReadingMutableContainers error:&error];
    if( error != nil )
    {
        return;
    }
    NSLog(@"unwrapped: %@", unwrapped);
}

Documentation

Web

iOS

Android

Cross-Platform

Alan iOS SDK

Set up an XСode project

Set up an XCode project with CocoaPods

Set up an XCode project manually

Integrate with Swift

Integrate with Objective-C

Add the AlanConfig object

Add the Alan button

Playing text via Alan

Sending a voice synchronized data event

Setting a visual state of the app

Calling a function from the voice script

Handle events from the Alan iOS SDK