Cisco Spark Android SDK

The Cisco Spark™ Android SDK

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

This SDK is built with Android SDK Tools 25 and requires Android API Level 21 or later.

Install
Usage
Contribute
License

Install

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

Add the following repository to your top-level build.gradle file:

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

Add the spark-android-sdk library as a dependency for your app in the build.gradle file:

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

Enable multidex support for your app:

android {
    defaultConfig {
        multiDexEnabled true
    }
}

Usage

To use the SDK, you will need Cisco Spark integration credentials. If you do not already have a Cisco Spark account, visit the Cisco Spark for Developers portal to create your account and register an 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 Android SDK area of the Cisco Spark for Developers site for more information about this SDK.

Examples

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

Create a new Spark instance using Spark ID 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<Void>() {
        @Override
        public void onComplete(Result<Void> result) {
            if (!result.isSuccessful()) {
                System.out.println("User not authorized");
            }
        }
    });
}

Create a new Spark instance using Guest ID authentication (JWT-based):

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

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

Create a new Cisco Spark space, add users to the space, and send a message:

// Create a Cisco Spark space:

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

// Add a user to a space:

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

// Send a message to a space:

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

Make an outgoing call:

spark.phone().dial("person@example.com", MediaOption.audioVideo(local, remote), new CompletionHandler<Call>() {
    @Override
    public void onComplete(Result<Call> 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();
        }
    }
});

Receive a call:

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

Make an room call:

spark.phone().dial(roomId, MediaOption.audioVideoSharing(new Pair<>(localView,remoteView),shareView), new CompletionHandler<Call>() {
    @Override
    public void onComplete(Result<Call> result) {
        Call call = result.getData();
        if (call != null) {
            call.setObserver(new CallObserver() {
                @Override
                public void onConnected(Call call) {

                }

             	//...

                @Override
                public void onCallMembershipChanged(CallMembershipChangedEvent callMembershipChangeEvent) {
                    CallMembership membership = callMembershipChangeEvent.getCallMembership();
                    if (callMembershipChangeEvent instanceof MembershipJoinedEvent) {

                    } else if (callMembershipChangeEvent instanceof MembershipLeftEvent) {

                    } else if (callMembershipChangeEvent instanceof MembershipDeclinedEvent) {

                    } else if (callMembershipChangeEvent instanceof MembershipSendingVideoEvent) {

                    } else if (callMembershipChangeEvent instanceof MembershipSendingAudioEvent) {

                    } else if (callMembershipChangeEvent instanceof MembershipSendingSharingEvent) {

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

Screen share (view only):

spark.phone().dial(roomId, MediaOption.audioVideoSharing(new Pair<>(localView,remoteView),shareView), new CompletionHandler<Call>() {
    @Override
    public void onComplete(Result<Call> result) {
        Call call = result.getData();
        if (call != null) {
            call.setObserver(new CallObserver() {
                @Override
                public void onConnected(Call call) {

                }

             	//...

                @Override
                public void onMediaChanged(MediaChangedEvent mediaChangedEvent) {
                    if (mediaChangedEvent instanceof RemoteSendingSharingEvent) {
                        if (((RemoteSendingSharingEvent) mediaChangedEvent).isSending()) {
                            mediaChangedEvent.getCall().setSharingRenderView(shareView);
                        } else if (!((RemoteSendingSharingEvent) mediaChangedEvent).isSending()) {
                            mediaChangedEvent.getCall().setSharingRenderView(null);
                        }
                    }
                }
            });
        }
        else {
            SparkError error = result.getError();
        }
    }
});

Contribute

Pull requests welcome. To suggest changes to the SDK, please fork this repository and submit a pull request with your changes. Your request will be reviewed by one of the project maintainers.

License

See LICENSE for details.