Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/webex/spark-android-sdk

This repo is DEPRECATED. Check our newer Android SDK
https://github.com/webex/spark-android-sdk

Last synced: about 7 hours ago
JSON representation

This repo is DEPRECATED. Check our newer Android SDK

Awesome Lists containing this project

README

        

This repo is DEPRECATED. Check our newer Android SDK: https://github.com/webex/webex-android-sdk

# Cisco Spark Android SDK

[![Travis CI](https://travis-ci.org/webex/spark-android-sdk.svg)](https://travis-ci.org/webex/spark-android-sdk)
[![license](https://img.shields.io/github/license/webex/spark-android-sdk.svg)](https://github.com/webex/spark-android-sdk/blob/master/LICENSE)

> 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 27** and requires **Android API Level 21** or later.

## Table of Contents

- [Install](#install)
- [Usage](#usage)
- [Contribute](#contribute)
- [License](#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](https://gradle.org):

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

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

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

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

3. Enable [multidex](https://developer.android.com/studio/build/multidex.html) support for your app:

```groovy
android {
defaultConfig {
multiDexEnabled true
}
}
```

4. Exclude rxjava.properties in your packagingOptions :

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

## 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](https://developer.ciscospark.com/) to create your account and [register an integration](https://developer.ciscospark.com/authentication.html#registering-your-integration). Your app will need to authenticate users via an [OAuth](https://oauth.net/) grant flow for existing Cisco Spark users or a [JSON Web Token](https://jwt.io/) for guest users without a Cisco Spark account.

See the [Android SDK area](https://developer.ciscospark.com/sdk-for-android.html) 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.

1. Create a new `Spark` instance using Spark ID authentication ([OAuth](https://oauth.net/)-based):

```java
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");
}
}
});
}
```

2. Create a new `Spark` instance using Guest ID authentication ([JWT](https://jwt.io/)-based):

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

3. Register the device to send and receive calls:

```java
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
}
}
});
```

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

```java
// Create a Cisco Spark space:

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

// Add a user to a space:

spark.memberships().create(roomId, null, "[email protected]", true, new CompletionHandler() {
@Override
public void onComplete(Result 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() {
@Override
public void onComplete(Result result) {
if (result.isSuccessful()) {
Message message = result.getData();
}
else {
SparkError error = result.getError();
}
}
});
```

5. Make an outgoing call:

```java
spark.phone().dial("[email protected]", 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();
}
}
});
```

6. Receive a call:

```java
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();
}
}
});
}
});
```
7. Make an room call:

```java
spark.phone().dial(roomId, MediaOption.audioVideoSharing(new Pair<>(localView,remoteView),shareView), new CompletionHandler() {
@Override
public void onComplete(Result 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();
}
}
});
```

8. Receive screen share:

```java
spark.phone().dial(roomId, MediaOption.audioVideoSharing(new Pair<>(localView,remoteView),shareView), new CompletionHandler() {
@Override
public void onComplete(Result 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();
}
}
});

```

9. Start/stop sharing screen:

```java
activeCall.startSharing(r -> Ln.d("startSharing result: " + r));
boolean isSharing = activeCall.isSendingSharing();
activeCall.stopSharing(r -> Ln.d("stopSharing result: " + r));
```

10. Post a message

```java
spark.message().post(
idOrEmail, // person id, email or room id
message, // text message to be sent
mentions, // list of Mention object
files, // list of files to be sent
new CompletionHandler() {
@Override
public void onComplete(Result result) {
if (result.isSuccessful()) {
// message sent success
} else {
// message sent failed
}
}
}));
```

11. Receive a message

```java
spark.message().setMessageObserver(
new MessageObserver() {
void onEvent(MessageEvent event) {
if (event instanceof MessageArrived) {
Message message = event.getMessage();
// new message arrived
} else if (event instanceof MessageDeleted) {
// message deleted
}
}
}
);
```

## 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

© 2016-2018 Cisco Systems, Inc. and/or its affiliates. All Rights Reserved.

See [LICENSE](https://github.com/ciscospark/spark-android-sdk/blob/master/LICENSE) for details.