Overview

Cisco Spark iOS SDK enables you to embed Cisco Spark calling and meeting experience into your iOS mobile application. The SDK provides APIs to make and receive audio/video calls. In order to receive audio/video calls, the user needs to be notified when someone is calling the user.

This sample Webhook/Push Notification Server demonstrates how to write a server application to receive Incoming Call Notification from Cisco Spark and use Apple Push Notification Service to notify the mobile application.

This sample is built upon apns4j and Sprint Boot. It is designed to be deployed and run on Heroku. But it can be deployed and run on other environments with minimal changes.

For more information about iOS remote notification, please see Apple developer guide.

How it works

Assuming this sample Webook/Push Notification Server has been deployed on the public Internet, the following describes the webhooks and push notification workflow step by step.

Register to the Apple Push Notification Service (APNs) when your iOS application is launching.
The APNs returns a device token to the application.

Register the device token returned by the APNs and the user Id of current user to the Webhook/Push Notification Server. The Server stores these information locally in a database.

let paramaters: Parameters = [
	"email": email,
	"voipToken": voipToken,
	"msgToken": msgToken,
	"personId": personId
]
Alamofire.request("https://example.com/register", method: .post, parameters: paramaters, encoding: JSONEncoding.default).validate().response { res in
	// ...
}

After the user logs into Cisco Spark，use Webhook API to create an webhook at Cisco Spark cloud. The target URL of the webhook must be the /webhook REST endpoint of this server. The URL has to be publicly accessible from the Internet.

spark.webhooks.create(name: "Incoming Call Webhook", targetUrl: targetUrl, resource: "callMemberships", event: "created", filter: "state=notified&personId=me") { res in
	switch res.result {
        case .success(let webhook):
        	// perform positive action
        case .failure(let error):
        	// perform negative action
    	}
}

The remote party makes a call via Cisco Spark.
Ciso Spark receives the call and triggers the webhook. The incoming call event is sent to the target URL, which should be /webhook REST endpoint of this Webhook/Push Notification server.
The Webhook/Push Notification Server looks up the device token from the database by the user Id in the incoming call event, then sends the notification with the device token and incoming call information to the APNs.
The APNs pushs notification to the iOS device.
Your iOS application gets the push notification and uses the SDK API to accept the call from Spark Cloud.

For more details about Step 1 and 2, please see Apple Push Notifications Guide

For more details about Step 3 and 6, please see Cisco Spark Webhooks Explained

Deployment

The sample application can be easily deployed as a Java application on the Heroku.

Create an Herko account and set up the Heroku environment.
Create a new Heroku app.

Clone the sample code to a local directory.

git clone git@github.com:ciscospark/spark-ios-sdk-example-push-notification-server.git

Copy your Apple Push Certificates to ./spark-ios-sdk-example-push-notification-server/.jdk-overlay/jre/lib/security.

Sending and receiving push notifications requires you to create Apple Push Certificates. For this sample application, you should create and upload three certificates corresponding, one for each type: Development, Production and VoIP Services.

Apple Push Certificates are generated from the Apple Developer Member Center which requires a valid Apple ID to login.

Deploy the application to Heroku.

heroku git:remote -a YOUR_APP_NAME
git add .
git commit -am "First Deploy"
git push heroku master

REST API endpoints and Usage

The sample Webhook/Push Notification server provides three REST API endpoints.

POST /webhook -- This REST API endpoint should be used as the target URL for Cisco Spark Webhooks Explained. Cisco Spark post the incoming call event to this endpoint.

Please see the implementation for more details.
POST /register -- This REST API endpoint should be used by the moible application to register the device token and user id to this sample server.

Please see the implementation for more details.
DELETE /register/{device_token} -- This REST API endpoint should be used to delete the registered device token.

Please see the implementation for more details.

webex/spark-ios-sdk-example-push-notification-server

Overview

How it works

Deployment

REST API endpoints and Usage