Cisco Spark

SDK for Android BETA

Integrate Cisco Spark into your Android apps

Features

Integrate the Android SDK into your Android apps to place and receive Cisco Spark video calls:

  • Audio and/or video 1:1 calling
  • Dial by email, Cisco Spark User ID, PSTN, or SIP address
  • Incoming call notification
  • DTMF
  • Create Teams, Spaces, and Memberships
  • Post messages
Getting Started Guide

If you are working with Android, Cisco Spark allows you to integrate secure and convenient Cisco Spark messaging and calling features in your Android apps.

The Cisco Spark Android SDK gives you the ability to customize your app and to seamlessly access Cisco Spark’s powerful collaboration features without ever having to leave your mobile app. Use the Android SDK to apply your own UI for customization and still use client-side API calls to embed Cisco Spark voice and video calling directly into your application. With the Cisco Spark Android SDK, you can also connect end users from your app to any Cisco Spark app/device and SIP device.

Overview

  • Create Cisco Spark Rooms
  • Post Cisco Spark Messages
  • Make and receive audio/video calls

Requirements

  • Android Studio 2.3 or later
  • Android SDK Tools 25 or later
  • Android API Level 21 or later
  • Java JDK 8
  • Gradle for dependency management
  • Cisco Spark Account
  • Use of this SDK requires the spark:all scope

Step 1: Integrate the Cisco Spark Android SDK

First, you need to add the following repository to your top-level build.gradle file of your project module in Android Studio.

To do this, open the Project Structure view and then open your build.gradle (Project: YourApplication Name) file. Then, add mavenCentral() underneath the allprojects -> repositories code blocks, as shown below:

allprojects {
    repositories {
        jcenter()
        maven {
            url 'https://devhub.cisco.com/artifactory/sparksdk/'
        }
    }
}

Step 2: Add the Cisco Spark Android SDK Library

Now you need to include the Cisco Spark Android SDK library module as a dependency for your app.

To do this, add the following code and configuration to the dependencies block of the build.gradle (Module: app) file, as shown below:

dependencies {
    compile('com.ciscospark:androidsdk:0.2.0@aar', {
        transitive = true
    })
}

Step 3: Enable Multidex Support and Update Packaging Options

In order for your app code to compile correctly after integration, you will need to enable multidex support for your app.

To do this, add multiDexEnabled true to the build.gradle (Module: app) file, under defaultConfig, as shown below:

android {
    defaultConfig {
        multiDexEnabled true
    }
}

Note: Enabling multidex support allows your app build process to generate more than one (DEX) file when you compile your app. See the description of multidex in the Android documentation for more information.

You will also need to exclude the rxjava.properties file. To do this, add these packagingOptions to the build.gradle (Module: app) file, as shown below:

packagingOptions {
    exclude 'META-INF/rxjava.properties'
}

Now, just sync the gradle dependencies to ensure that everything integrates properly.

Keep reading for details about how to use the Cisco Spark Android SDK with your application, starting with authenticating the user, and then moving on to creating rooms and sending messages.

App Integration and Authentication

Before your app can use Cisco Spark on behalf of another user, you will need to register a Cisco Spark Integration. Your app will either need to authenticate users via an OAuth grant flow for existing Cisco Spark users, or via a JSON Web Token for guest users that do not have a Cisco Spark account.

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.

See the examples below for creating new Spark instances for existing Cisco Spark users or for guest users who do not have a Cisco Spark account.

Example #1 - Create a new Spark instance using Cisco Spark authentication (OAuth-based):

String clientId = "YOUR_CLIENT_ID";
String clientSecret = "YOUR_CLIENT_SECRET";
String scope = "spark:all";
String redirectUri = "Sparkdemoapp://response";

OAuthWebViewAuthenticator authenticator = new OAuthWebViewAuthenticator(clientId, clientSecret, scope, redirectUri);
Spark spark = new Spark(activity.getApplication(), authenticator)
if (!authenticator.isAuthorized()) {
    authenticator.authorize(webView, new CompletionHandler() {
        @Override
        public void onComplete(Result result) {
            if (!result.isSuccessful()) {
                System.out.println("User not authorized");
            }
        }
    });
}

Example #2 - Create a new Spark instance using Guest Issuer authentication (JWT-based):

JWTAuthenticator authenticator = new JWTAuthenticator();
Spark spark = new Spark(activity.getApplication(), authenticator);
if (!authenticator.isAuthorized()) {
    authenticator.authorize(myJwt);
}

Using Cisco Spark with your App

Now that you're authenticated, you can use Cisco Spark. You can create a room, add users, and post messages using the SDK.

Create a room:

spark.rooms().create("Hello World", null, new CompletionHandler() {
    @Override
    public void onComplete(Result result) {
        if (result.isSuccessful()) {
            Room room = result.getData();
            String roomId = room.getId();
        }
        else {
            SparkError error = result.getError();
        }
    }
});

Add users to the room:

spark.memberships().create(roomId, null, "person@example.com", true, new CompletionHandler() {
    @Override
    public void onComplete(Result result) {
        if (result.isSuccessful()) {
            Membership membership = result.getData();
        }
        else {
            SparkError error = result.getError();
        }
    }
});

Post messages to the room:

spark.messages().post(roomId, null, null, "Hello there", null, null, new CompletionHandler() {
    @Override
    public void onComplete(Result result) {
        if (result.isSuccessful()) {
            Message message = result.getData();
        }
        else {
            SparkError error = result.getError();
        }
    }
});

Cisco Spark Audio/Video Calling

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

First, you need to register the device in order to send and receive calls:

spark.phone().register(new CompletionHandler() {
    @Override
    public void onComplete(Result result) {
        if (result.isSuccessful()) {
            // Device registered
        }
        else {
            // Device not registered, and calls will not be sent or received
        }
    }
});

Once registration is complete, you can make an outgoing call, as shown below:

spark.phone().dial("person@example.com", MediaOption.audioVideo(local, remote), new CompletionHandler() {
    @Override
    public void onComplete(Result result) {
        Call call = result.getData();
        if (call != null) {
            call.setObserver(new CallObserver() {
                @Override
                public void onRinging(Call call) {

                }

                @Override
                public void onConnected(Call call) {

                }

                @Override
                public void onDisconnected(CallDisconnectedEvent
                callDisconnectedEvent) {

                }

                @Override
                public void onMediaChanged(MediaChangedEvent
                mediaChangedEvent) {

                }
            });
        }
        else {
            SparkError error = result.getError();
        }
    }
});

These calls can be made to Cisco 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.

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

// Send DTMF
Call.sendDTMF(dtmfEvent, new CompletionHandler() {
    @Override
    public void onComplete(Result result){

    }
});

To receive a call:

spark.phone().setIncomingCallListener(new Phone.IncomingCallListener() {
    @Override
    public void onIncomingCall(Call call) {
        call.answer(MediaOption.audioVideo(local, remote), new CompletionHandler() {
            @Override
            public void onComplete(Result result) {
                if (result.isSuccessful()) {
                    // success
                }
                else {
                    SparkError error = result.getError();
                }
            }
        });
    }
});

Complete Demo App

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

Troubleshooting the Android SDK

If you're having trouble with the Android SDK, here's some more information to help troubleshoot the issue.

SDK Requirements

Review the following SDK requirements to make sure you're using the correct minimum versions of Android Studio, Java JDK, etc.:

  • Android Studio 2.3 or later
  • Android SDK Tools 25 or later
  • Android API Level 21 or later
  • Java JDK 8
  • Gradle for dependency management
  • A Cisco Spark account and integration with the spark:all scope

View the System Logs

The Cisco Spark Android SDK uses the Android system logger utility to collect log messages that will allow you to define problem areas when troubleshooting.

Use the Logcat command-line tool to collect, view, and filter all SDK logs. The Android SDK provides the option to display all messages or just the messages that indicate the most severe errors. Set the log level to verbose to display all errors. See Write and View Logs with Logcat for more information.

spark.setLogLevel(Spark.LogLevel.VERBOSE);

Firewall Ports

The Android SDK makes use of the following network ports. If you're encountering connection issues, make sure there aren't any firewalls blocking or preventing communication over these ports.

Service Protocol Port(s)
Messaging HTTPS 443
Notifications WebSocket 443
Calls HTTPS 443
Media RTP/SRTP over UDP/TCP 33434-33598, 8000-8100 or 33434 (shared port)

SDK Dependencies

For more information about dependencies of the Android SDK, please refer to their documentation:

App Crashes

If your app is crashing, running a stack trace may help you determine the root cause. Please see Android’s Diagnose the Crashes for more information about determining the cause of Android app crashes.

Getting Support

If you're stumped, contact Cisco Spark's DevSupport team for more help with the SDK.