This section contains short examples of what it looks like to instantiate the SDK and make a query request, along with some information on the callback structure and what all the notifications mean. Note: This is a short reference. Be sure to see the full documentation to get a better understanding of our service.

Callback structure

public protocol Callback: AnyObject {

    associatedtype C : Context
    associatedtype E : Entities
    
    func success(response: StreamResponse<C,E>)
    
    func failure(error: VoysisError)
    
    func recordingStarted()
    
    func queryResponse(queryResponse: QueryResponse)
    
    func recordingFinished(reason: FinishedReason)
    
    func audioData(data: Data)
}

public extension Callback {

    func audioData(data: Data) {
        //no implementation
    }

    func recordingStarted() {
        //no implementation
    }

    func queryResponse(queryResponse: QueryResponse) {
        //no implementation
    }

    func recordingFinished(reason: FinishedReason) {
        //no implementation
    }
}

Service instantiation and query request

A Service object is instantiated via the ServiceProvider.make(config) method by first creating a config object using refreshToken, URL and VAD setting.

Be sure to read the full documentation here for detailed explosions on the following.

class ViewController: UIViewController, Callback {
    private let config = Config(url: URL(string: "wss://INSERT_URL/websocketapi")!, refreshToken: "INSERT_TOKEN")
    private let context : CommerceContext? = nil
    private lazy var voysis = Voysis.ServiceProvider.make(config: config)

    @IBAction func buttonClicked(_ sender: Any) {
        voysis.startAudioQuery(context: self.context, callback: self)
    }

    func success(response: StreamResponse<CommerceContext, CommerceEntities>) {
        // Do something
    }

    func failure(error: VoysisError) {
        // Do Something
    }
}

Context & Entities

Above you will notice that Callback.success takes two generic types: Context and Entities. The JSON query response will contain context and entities objects whose content will vary depending on the customer's specific service. In order to play nicely with Swifts codable protocol the user is required to define these objects in their own codebase beforehand and set them as seen above. for example:

Given the following json structure for context:

"context": {
  "keywords": [
    "leather",
    "handbags"
  ],
  "attributes": {
    "color": "red"
  },
  "price": {
    "type": "lessThan",
    "value": 200
  },
  "sortBy": "rating"
}

The user will create the following struct in their own codebase and reference it as displayed in the example above.

public struct ExampleContext: Context {
    public var keywords: [String]? 
    public var attributes: [String: [String]]?
    public var price: Price?
    public var sortBy: String?

    public init() {
    }
}

public struct Attribute: Codable {
    public let value: [String]?
    public let key: String
}

public struct Price: Codable {
    public let type: String?
    public var value: String?
    public var from: String?
    public var to: String?
}

EventType

func recordingStarted(): Called when the microphone has been turned on and the user can begin speaking. This should happen immediately after the SoundBite prompt completes. Recorded audio will be stored in a queue until a connection has been made with the server.
queryResponse(queryResponse: QueryResponse): Called when a successful connection has been made with the server. Once this is called, stored audio will be sent through the connection and will continue to stream until recording completes. The QueryResponse object contains information about the connection, and can be parsed or ignored by the user.
func recordingFinished(reason: FinishedReason): Called when the microphone is turned off. This can happen for several reasons.
- 1. the user manually clicks finish() or cancel().
- 1. Recording timeout: There is a max recording length of 320000 bytes (roughly 10 seconds) imposed on the client. Once this is reached the microphone will be turned off.
- 1. VAD is initiated: On a Websocket, if the server detect that the user has stopped speaking a notification will be sent to the SDK to indicate that recording should stop.
- 1. Error case: If an error occurs recording will stop.
func success(response: StreamResponse<C,E>): Called when a successful response has been returned from the server. The StreamResponse object will contain information about the response along with intent, entities and context.
func failure(error: VoysisError): Called in the case of an error.
func audioData(data: Data): Called when an audio buffer fills and is sent to the server.

Full documentation can be found on the Github page of the iOS SDK here.
Refer to it for specific information or download.