Cisco Spark iOS SDK

The Cisco Spark iOS SDK makes it easy to integrate secure and convenient Cisco Spark messaging and calling features in your iOS apps.

This SDK is written in Swift 4 and requires iOS 10 or later.

Install
Usage
Upgrade 1.3.1 to 1.4.0
License

Install

Assuming you already have an Xcode project, e.g. MySparkApp, for your iOS app, here are the steps to integrate the Spark iOS SDK into your Xcode project using CocoaPods:

Install CocoaPods:
```
gem install cocoapods
```
Setup CocoaPods:
```
pod setup
```

Create a new file, Podfile, with following content in your MySparkApp project directory:

source 'https://github.com/CocoaPods/Specs.git'

use_frameworks!

target 'MySparkApp' do
  platform :ios, '10.0'
  pod 'SparkSDK'
end

target 'MySparkAppBroadcastExtension' do
    platform :ios, '11.2'
    pod 'SparkBroadcastExtensionKit'
end

Install the Spark iOS SDK from your MySparkApp project directory:
```
pod install
```

Usage

To use the SDK, you will need Cisco Spark integration credentials. If you do not already have a Cisco Spark account, visit Spark for Developers to create your account and register your integration. Your app will need to authenticate users via an OAuth grant flow for existing Cisco Spark users or a JSON Web Token for guest users without a Cisco Spark account.

See the iOS SDK area of the Spark for Developers site for more information about this SDK.

Example

Here are some examples of how to use the iOS SDK in your app.

Create the Spark instance using Spark ID authentication (OAuth-based):

let clientId = "$YOUR_CLIENT_ID"
let clientSecret = "$YOUR_CLIENT_SECRET"
let scope = "spark:all"
let redirectUri = "Sparkdemoapp://response"

let authenticator = OAuthAuthenticator(clientId: clientId, clientSecret: clientSecret, scope: scope, redirectUri: redirectUri)
let spark = Spark(authenticator: authenticator)

if !authenticator.authorized {
    authenticator.authorize(parentViewController: self) { success in
        if !success {
            print("User not authorized")
        }
    }
}

Create the Spark instance with Guest ID authentication (JWT-based):

let authenticator = JWTAuthenticator()
let spark = Spark(authenticator: authenticator)

if !authenticator.authorized {
    authenticator.authorizedWith(jwt: myJwt)
}

spark.phone.register() { error in
    if let error = error {
        // Device not registered, and calls will not be sent or received
    } else {
        // Device registered
    }
}

Use Spark service:

spark.rooms.create(title: "Hello World") { response in
    switch response.result {
    case .success(let room):
        // ...
    case .failure(let error):
        // ...
    }
}

// ...

spark.memberships.create(roomId: roomId, personEmail: email) { response in
    switch response.result {
    case .success(let membership):
        // ...
    case .failure(let error):
        // ...
    }
}

Make an outgoing call:

spark.phone.dial("coworker@acm.com", option: MediaOption.audioVideo(local: ..., remote: ...)) { ret in
    switch ret {
    case .success(let call):
        call.onConnected = {
            // ...
        }
        call.onDisconnected = { reason in
            // ...
        }
    case .failure(let error):
        // failure
    }
}

Receive a call:

spark.phone.onIncoming = { call in
    call.answer(option: MediaOption.audioVideo(local: ..., remote: ...)) { error in
    if let error = error {
        // success
    }
    else {
        // failure
    }
}

Make an room call:

spark.phone.dial(roomId, option: MediaOption.audioVideo(local: ..., remote: ...)) { ret in
    switch ret {
    case .success(let call):
        call.onConnected = {
            // ...
        }
        call.onDisconnected = { reason in
            // ...
        }
        call.onCallMembershipChanged = { changed in
            switch changed {
            case .joined(let membership):
                //
            case .left(let membership):
                //
            default:
                //
            }                
        }            
    case .failure(let error):
        // failure
    }
}

Screen share (view only):

spark.phone.dial("coworker@acm.com", option: MediaOption.audioVideoScreenShare(video: (local: ..., remote: ...))) { ret in
    switch ret {
    case .success(let call):
        call.onConnected = {
            // ...
        }
        call.onDisconnected = { reason in
            // ...
        }
        call.onMediaChanged = { changed in
            switch changed {
                ...
            case .remoteSendingScreenShare(let sending):
                call.screenShareRenderView = sending ? view : nil
            }
        }
    case .failure(let error):
        // failure
    }
}

Post a message:

spark.messages.post(personEmail: email, text: "Hello there") { response in
    switch response.result {
    case .success(let message):
        // ...
    case .failure(let error):
        // ...
    }
}

Receive a message:

spark.messages.onEvent = { messageEvent in
    switch messageEvent{
    case .messageReceived(let message):
        // ...
        break
    case .messageDeleted(let messageId):
        // ...
        break
    }
}

Screen share (sending):

11.1 In your containing app:

spark.phone.dial("coworker@acm.com", option: MediaOption.audioVideoScreenShare(video: ..., screenShare: ..., applicationGroupIdentifier: "group.your.application.group.identifier"))) { ret in
    switch ret {
    case .success(let call):
        call.oniOSBroadcastingChanged = {
            event in
            if #available(iOS 11.2, *) {
                switch event {
                case .extensionConnected :
                    call.startSharing() {
                        error in
                        // ...
                    }
                    break
                case .extensionDisconnected:
                    call.stopSharing() {
                        error in
                        // ...
                    }
                    break
                }
            }
        }
        }
    case .failure(let error):
        // failure
    }
}

11.2 In your broadcast upload extension sample handler:

override func broadcastStarted(withSetupInfo setupInfo: [String : NSObject]?) {
    // User has requested to start the broadcast. Setup info from the UI extension can be supplied but optional.
    SparkBroadcastExtension.sharedInstance.start(applicationGroupIdentifier: "group.your.application.group.identifier") {
        error in
        if let sparkError = error {
           // ...
        } else {
            SparkBroadcastExtension.sharedInstance.onError = {
                error in
                // ...
            }
            SparkBroadcastExtension.sharedInstance.onStateChange = {
                state in
                // state change
            }
        }
    }
}

override func broadcastFinished() {
    // User has requested to finish the broadcast.
    SparkBroadcastExtension.sharedInstance.finish()
}

override func processSampleBuffer(_ sampleBuffer: CMSampleBuffer, with sampleBufferType: RPSampleBufferType) {
    switch sampleBufferType {
        case RPSampleBufferType.video:
            // Handle video sample buffer
            SparkBroadcastExtension.sharedInstance.handleVideoSampleBuffer(sampleBuffer: sampleBuffer)
            break
        case RPSampleBufferType.audioApp:
            // Handle audio sample buffer for app audio
            break
        case RPSampleBufferType.audioMic:
            // Handle audio sample buffer for mic audio
            break
    }
}

11.3 Get more technical details about the Containing App & Broadcast upload extension and Set up an App Group

Upgrade SDK 1.3.1 to 1.4.0 Breaking Changes

Minimum Deployment Target: ~~8.0~~ => 10.0
Support Swift Language Version: ~~3.0~~ => 4.0
If you were using ‘MediaRenderView’, need to add import SparkSDK.
If you were using ‘MediaRenderView’ class in storyboard, set the view’s module to ‘SparkSDK’.

License