Cisco Spark

SDK for iOS

Integrate Cisco Spark into your iOS apps quickly with the Cisco Spark SDK for iOS

Features

Integrate the iOS SDK into iOS apps to place and receive Spark video calls:

  • Audio and/or video 1:1 calling
  • Dial by email, Spark User ID, or SIP address
  • Call and event controls, including DTMF
  • Audio and video call control
Getting Started Guide

The Spark iOS SDK is the easiest way to integrate Cisco Spark into your iOS app.

Overview

  • Create Spark rooms
  • Create Spark teams
  • Add users/members/moderators into rooms/teams
  • Post messages/share attachments
  • Make and receive audio/video calls

Requirements

  • iOS app using Swift 3
  • Xcode 8.0 or later
  • iOS 9 or later
  • CocoaPods
  • Spark Account
  • Use of this SDK requires the spark:all scope

Step 1: Prepare the Workspace

Install and Set Up CocoaPods

gem install cocoapods
pod setup

Workspace Creation
  • Open Xcode and create a new project:
    • Click File > New > Project, select the iOS > Application > Single View Applicaition template, and click Next.
    • Set the Product Name to "Sparkdemoapp", Organization name to "com.example", and Launguage to Swift. Click Next.
    • Select a destination directory for the project and click Create.
  • Close the project by clicking File > Close Project.
  • Go to the directory Sparkdemoapp.xcodeproj.
  • Create Podfile as below

    source 'https://github.com/CocoaPods/Specs.git'
    platform :ios, '9.0'
    use_frameworks!
    
    target 'Sparkdemoapp' do
    pod 'SparkSDK'
    end
    

  • Install SparkSDK

    pod install
    

  • Open the Xcode workspace instead of the project file, otherwise you will face issues with Frameworks dependencies. In order to use the SDK in your project, simply:

    import SparkSDK
    

Step 2: App Integration and OAuth 2

You must first register a Spark Integration before your application can use Spark on behalf of a user. Once registration is complete, you will get a Client ID and Client Secret for use with the app. These can be used to generate a token with the proper scopes, but luckily the iOS SDK has a method which will perform this step for you:

class LoginViewController: UIViewController {

  @IBAction func loginWithSpark(sender: AnyObject) {
    let clientId = "..."
    let clientSecret = "..."
    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")
        }
      }
    }
  }
}

Step 3: Let's Try Some Spark Messaging

Now that you're authenticated, you can now use Spark. It's easy to create a room, add users, and post messages using the SDK.

To create a room:

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

To add users to the room:

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

Post a message into the room:

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

Add a message with an attachment:

spark.messages.post(personEmail: email, files: "http://example.com/hello_world.jpg") { response in
  switch response.result {
  case .success(let message):
      // ...
  case .failure(let error):
      // ...
  }
}

Teams are quite useful if you want to create a set of rooms for only certain members of the team. Teams also have an independent membership management interface for inviting/deleting/listing users and adding a moderator to the team room.

To create a team:

spark.teams.create(name: "Hello World") { response in
  switch response.result {
  case .success(let team):
      // ...
  case .failure(let error):
      // ...
  }
}

To add users to the team:

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

Set moderator for the team:

spark.teamMemberships.create(teamId: teamId, personEmail: email, isModerator: true) { response in
  switch response.result {
  case .success(let membership):
      // ...
  case .failure(let error):
      // ...
  }
}

Complete code snippet for rooms and team memberships:

// IM example
spark.rooms.create(title: "Hello World") { response in
  switch response.result {
  case .success(let room):
    print("\(room.title!), created \(room.created!): \(room.id!)")
    if let email = EmailAddress.fromString("coworker@acm.com"), let roomId = room.id {
      spark.memberships.create(roomId: roomId, personEmail: email) { response in
        spark.memberships.list { response in
          if let memberships = response.result.data {
            for membership in memberships {
              print("\(String(describing: membership.personEmail?.toString()))")
            }
          }
        }
        spark.messages.post(roomId: roomId, text: "Hello World") { response in

        }
      }
    }
  case .failure(let error):
    print("Error: \(error.localizedDescription)")
  }
}

Step 4: Spark Audio/Video Calling

This is the most significant SDK feature which enables users to make and receive audio/video calls using Spark. Calling in the SDK is very easy to use.

First, we need to register the device:

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

Once registration is complete, make a call:

// Make a 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
  }
}

The calls can be made to Spark users/devices, Telepresence systems, SIP devices, and regular telephones. If the user calls a telephone system such as an IVR, the SDK also supports DTMF transport so users can navigate IVR menus. iOS users can also view the content shared from any Telepresence system. It is a fully-integrated collaboration SDK.

To send DTMF, simply invoke call.send(dtmf:completionHandler:):

// Send DTMF
if let dtmfEvent = dialButton.text {
  call.send(dtmf: dtmfEvent, completionHandler: nil)
}

In order to receive a call, the callback function callIncoming() is used.

Handle the incoming call event:

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

Complete Demo App

A complete demo application is available to see the complete functionality of the SDK.