Skip to content

Migration Guide from SDK 2.x to 3.x

Jump to bottom
adamrangs edited this page Aug 8, 2022 · 1 revision

Cisco Webex Android SDK Migration Guide

The Cisco Webex™ Android SDK Version 3+

The Cisco Webex Android SDK Version 3.0.0 is a major rewrite of version 2.x. It introduces a completely new architecture based on the same technology that powers the native Webex apps. This includes a lot of enhancements to the performance of the SDK most notably with the introduction of a local data warehouse to cache all the spaces, messages, people, calls, and much more. It also introduces a revolutionary new Catch up API that avoids redundant fetching of information from servers. Future updates and feature parity with the native clients will also be quicker than what it is at present. The v3 SDK is built-in Kotlin language with Android SDK Tools 29 and requires Android API Level 24 or later. If you have developed an app with Cisco Webex SDK version 2.x, this guide will help you in migrating from Webex SDK version 2 to version 3.

Table of Contents

Advantages

  • Unified feature set: Meeting, Messaging, and CUCM calling.
  • Greater feature velocity and in parity with the Webex mobile app.
  • Easier for developers community: SQLite is bundled for automatic data caching.
  • Greater quality as it is built on a more robust infrastructure.

Notes

  • Since, this SDK is built in Kotlin language. So, the transition between java and kotlin has to be taken care of if the app is built in Java language.
  • From 3.0.0 onwards, we have a new entry point for the SDK. i.e: webex.initialize(handler: CompletionHandler<Void>). This needs to be invoked before any other API(even before Auth). This method internally bootstraps the SDK and all its components.
  • Integrations created earlier will not work with v3 because they are not entitled to the scopes required by v3. You can either raise a support request to enable these scopes for your appId or you could create a new Integration that's meant to be used for v3. This does not affect Guest Issuer JWT token-based sign-in.
  • We do not support external auth code login anymore.
  • Refreshing OAuth access token logic is now automatically handled by the SDK using timers. So we've removed this API from OAuthAuthenticator.
  • Webex.getLogFileUri(): You can use this to extract the WebexSDK logs as a zip file.
  • Currently all resource ids that are exposed from the SDK are barebones GUIDs. You cannot directly use these ids to make calls to webexapis.com. You'll need to call Webex.base64Encode(type: ResourceType, resource: String, handler: CompletionHandler<String>) to get a base64 encoded resource. However, you're free to interchange between base64 encoded resource ids and barebones GUID while providing them as input to the SDK APIs.
  • You can add android:extractNativeLibs="true" inside your <application> tag in your Manifest file to reduce the generated apk size.

Integration

Option 1

  1. Put AAR file in libs folder of your Android project

  2. Open the project level Gradle file and add the following lines under the repositories tag, which is nested under allprojects.

    allprojects {
  repositories {
      flatDir { dirs 'aars'} //add this line
  }
}

  3. Add the following dependency in module level Gradle file and press sync-now

    implementation files('libs/WebexSDK.aar')

Option 2

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

    allprojects {
    repositories {
        maven {
            url 'https://devhub.cisco.com/artifactory/webexsdk/'
        }
    }
}

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

    dependencies { 
    implementation 'com.ciscowebex:androidsdk:3.0.0@aar'
}

Examples of transition

Here are some examples in Java to transition from Webex SDK v2 to Webex SDK v3:

  1. If you're using JWTAuthenticator authorization. In this version, we have added a completion handler which gets invoked when the authorization process is done.

    Previous syntax:

    jwtAuthenticator.authorize(jwt);

    Current syntax using CompletionHandler:

    jwtAuthenticator.authorize(jwt, CompletionHandler { result ->
     if (result.error != null) {
         // Login failed
     } else {
         // Login success
     }
 })

  2. Instantiating OAuthWebViewAuthenticator. We were using client scope as a constructor argument which is now removed because the scope is added internally. Also now we require a valid email to be passed in, as this required discovering which cluster the user belongs to.

    Previous syntax:

    OAuthWebViewAuthenticator authenticator = new OAuthWebViewAuthenticator(clientId, clientSec, scope, redirect);

    Current syntax:

    val authenticator = OAuthWebViewAuthenticator(clientId, clientSec, redirect, email)

val webex = Webex(applicationContext, authenticator)
webex.enableConsoleLogger(true)
webex.setLogLevel(Webex.LogLevel.VERBOSE)

webex.initialize(CompletionHandler { result ->
    if (result.error != null) {
        //already authorised
    } else {
        authenticator.authorize(loginWebview, CompletionHandler { result ->
                if (result.error != null) {
                    //Handle the error
                }else{
                    //Authorization successful
                }
            })
    }
})

  3. Phone.register() API is no more required because this happens at the time of login internally. You have to comment/remove this.

  4. Phone.deregister() API is no more required. You have to comment/remove this.

Clone this wiki locally