WARNING: This is a beta release of the Voysis iOS SDK.
Voysis iOS Swift SDK
This document provides a brief overview of the Voysis iOS SDK. This is an iOS library that facilitates sending voice queries to a Voysis instance. The SDK streams audio from the device microphone to the Voysis backend servers when called by the client application.
Documentation
The full documentation for the voysis api can be found here: Voysis Developer Documentation
Requirements
- iOS 8.0+
- Xcode 9.0+
- Swift 4.0+
Overview
The Voysis.Service
class is the main interface used to process voice recognition requests.
It is accessed via the static Voysis.ServiceProvider.make(config: Config(url : "http://ADD-URL.com/websocketapi"))
method.
The sdk communicates to the network using a Websocket connection accomplished using the Starscream.framework
.
The iOS core library, Audio Toolbox Audio Queue Services
is used for recording the users voice.
Config
To create a service instance you need to provide config information at construction time. The config file is comprised of several fields.
-
url - URL: This is the endpoint that network requests will be executed against. The url is provided when your Voysis service is delivered. To sign up for a Voysis service visit our homepage
-
refreshToken - String: The refresh token is used for authenticating unique users and for refreshing session tokens. This is all taken care of from within the library once the
refreshToken
is provided. For information on how to generate a refresh token see here -
userId - String?: This is an optional UUID used for identifying users to improve query results over time. See here for more details.
Context - Entities
One of the features of using the Voysis service is that different json response types can be returned depending on what service you're subscribed to.
The json objects which vary in type are Context
and Entities
. see Api Docs for information.
In order to facilitate this in the sdk and avail of the swift 4.0 Codable
serialization protocol, the object structure for Context
and Entities
must be setup by the user and added as generic parameters in the success callback. See the demo application and Usage below for an example of this in action.
Usage
- The first step is to create a
Voysis.Service
instance.
let voysis = Voysis.ServiceProvider.Make(config: Config(url: URL(string: "//INCLUDE-URL-HERE")!, refreshToken: "REFRESH-TOKEN"))
- Next: to make a request, call service.startAudioQuery with the mandatory Callback parameter and optional voysis Context (See context section below for details).
class ViewController: UIViewController, Callback {
...
@IBAction func buttonClicked(_ sender: Any) {
voysis.startAudioQuery(context: self.context, callback: self)
}
func success(response: StreamResponse<CommerceContext, CommerceEntities>) {
// Mandatory: called when final response returned from server.
}
func failure(error: VoysisError) {
// Mandatory: called when any error occurs
}
func recordingStarted() {
//Optional: called when microphone begins recording.
}
func queryResponse(queryResponse: QueryResponse) {
//Optional: called when successful connection is made to the server.
}
func recordingFinished(reason: FinishedReason) {
//Optional: called when recording stops. Includes finishedReason enum.
}
func audioData(data: Data) {
//Optional: returns audio data to the user that can be used generating for dynamic animations, analytics etc.
}
}
Integration - Carthage
Check out the Carthage docs on how to add and install.
To integrate the VoysisSdk into your Xcode project using Carthage, specify it in your Cartfile:
github "/voysis/voysis-ios"
- Once added, run
carthage update --no-use-binaries --platform iOS
from within your projects root directory. - Next, from within xCode, in the tab bar at the top of that window, open the "General" panel.
- Click on the
+
button under the "Embedded Binaries" section. - Click
Add Other
- Navigate to {{YOUR_PROJECT}}/Carthage/Build/iOS and click the
Voysis.framework
andStarscream.framework
Manual Integration - Embedded Framework
Note: This project requires Carthage to download the Starscream Websocket dependency.
Adding Voysis Sdk
-
First clone the project. Next, open the new
Voysis
folder, and drag theVoysis.xcodeproj
into the Project Navigator of your application's Xcode project.It should appear nested underneath your application's blue project icon. Whether it is above or below all the other Xcode groups does not matter.
-
Select your application project in the Project Navigator (blue project icon) to navigate to the target configuration window and select the application target under the "Targets" heading in the sidebar.
-
In the tab bar at the top of that window, open the "General" panel.
-
Click on the
+
button under the "Embedded Binaries" section. -
You will see the
Voysis.framework
nested inside aProducts
folder. -
Select the
Voysis.framework
for iOS.
Adding Starscream
- From within the Voysis directory run
carthage update --no-use-binaries --platform iOS
to download the Starscream.framework. - Again Click on the
+
button under the "Embedded Binaries" section. - Click
Add Other
. - Navigate to Voysis/Carthage/Build/iOS and click the Starscream.framework.
IMPORTANT NOTE
As of iOS10 you will need to include NSMicrophoneUsageDescription
in the application Info.plist.