Platform DocumentationPlatform ChangelogAPI ReferencePush & In-App SDKsSDK Release Notes
Push & In-App SDKs
FAQsWebsite

Android SDK Quick Start Guide (Modular)

The Webex Connect Android SDK provides a messaging framework that enables app developers to integrate Webex Connect's In-App and Push messaging services within their mobile applications.

Suggest Edits

The Webex Connect Android SDK provides a messaging framework that enables app developers to integrate Webex Connect's In-App and Push messaging services within their mobile applications.

With the transition to a modularized SDK, developers now have the flexibility to integrate only the specific modules of Webex Connect Android SDK that they need for their applications, thereby reducing their app size.

This guide will take you through all the steps required to integrate the modularized Webex Connect Android SDK within an application.

Prerequisites

The minimum requirements to use the Webex Connect SDK are:

ComponentRequirement
Android Operating SystemAndroid OS 5.0 (API 21) and higher.
Software Latest version of Android Studio
 Webex Connect Android SDK
Accounts- A valid Google account (required only if you're using FCM push services).
- A valid HMS account (required only if you're using HMS push services).
- An active Webex Connect account.

OS Version Support

Please ensure that your application targets these versions to take full advantage of the features and capabilities offered by the Webex Connect Android SDK. For the best performance and compatibility, we recommend always using the latest stable version of the SDK.

SDK VersionMin Supported OSTLS Support
3.0.0 and higherAndroid OS 5.0 (API 21)TLS 1.1 / 1.2 - Android OS 5.0+ (API 21+)

SDK Modules

Webex Connect SDK is structured into modular components, each designed to offer specific functionality. Please follow the below table to get more details of each module and its functionality. This will help you to understand what's available in each module and decide which modules you want to integrate into your applications.

ModuleDescription
webexconnect-coreThe core module is the foundation of the Webex Connect SDK. It provides essential functionality that all other modules depend on, including initialization, configuration, registration, and shared utilities.
webexconnect-pushThe push module enables your application to receive and handle push notifications. It abstracts the underlying push notification service, providing customized support for notification management.
webexconnect-fcmThe fcm module integrates Firebase Cloud Messaging to handle push notifications for devices with Google Play Services.
webexconnect-hmsThe hms module integrates Huawei Mobile Services to handle push notifications for devices with Huawei Mobile Services.
webexconnect-inappmessagingThe inappmessaging module offers both one-way and two-way messaging capabilities for your app.

Configuration Tasks

To use the Webex Connect SDK within your application follow these tasks in sequence:

  1. Configure a Mobile App Asset
  2. Code Integration

Code Integration

Follow the below steps to integrate Webex Connect Android SDK in your application:

a. Import the SDK

b. Configure Android Manifest

c. Add IMIconnectConfig.properties file

d. Configure Proguard Rules

e. Initialize the SDK

f. Register a Device

a. Import the SDK

Configure Android Gradle

Step 1: Make the following changes to your gradle file.

//Add this to your project-level build.gradle file
plugins {
  id("com.android.application") version "7.3.0" apply false
  // ...

  // Add the dependency for the Google services Gradle plugin
  id("com.google.gms.google-services") version "4.3.10" apply false
}

//Add this to your project-level build.gradle file
plugins {
  id 'com.android.application' version '7.3.0' apply false
  // ...

  // Add the dependency for the Google services Gradle plugin
  id 'com.google.gms.google-services' version '4.3.10' apply false
}

//Add this to your app-level build.gradle file.
buildscript {
    dependencies {
        //...
        // Add the AppGallery Connect plugin configuration. Please refer to AppGallery Connect Plugin Dependency to select a proper plugin version. 
        classpath("com.huawei.agconnect:agcp:1.9.1.301")
    }
}

//Add this to your project-level settings.gradle file.
pluginManagement {
    repositories {
        //...
        // Configure the Maven repository address for the HMS Core SDK.
        maven(url = "https://developer.huawei.com/repo/")
    }
}
dependencyResolutionManagement {
    repositories {
        //...
        // Configure the Maven repository address for the HMS Core SDK.
        maven(url = "https://developer.huawei.com/repo/")
    }
}

//Add this to your app-level build.gradle file
buildscript {
    dependencies {
        //...
        // Add the AppGallery Connect plugin configuration. Please refer to AppGallery Connect Plugin Dependency to select a proper plugin version. 
        classpath 'com.huawei.agconnect:agcp:1.9.1.301'
    }
}

//Add this to your project-level settings.gradle file.
pluginManagement {
    repositories {
        //...
        // Configure the Maven repository address for the HMS Core SDK.
        maven { url 'https://developer.huawei.com/repo/' }
    }
}
dependencyResolutionManagement {
    //...
    repositories {
        //...
        // Configure the Maven repository address for the HMS Core SDK.
        maven { url 'https://developer.huawei.com/repo/' }
    }
}

Import the SDK

The Webex Connect Android SDK can be imported with one of the following methods.

  1. Method 1: Importing via Maven Central.
  2. Method 2: Integrating manually by downloading the SDK.

Method 1: Importing via Maven Central

Add the following lines within the dependencies section of your app-build.gradle.

Below is the sample code to import via maven central.

🚧

Important

You should not include both FCM and HMS modules within the same build variant.

dependencies {
  
  //FCM Module - Required to use Firebase Cloud Messaging as the push provider.
  implementation 'com.webex.connect:webexconnect-fcm:3.0.0'

  //HMS Module - Required to use Huawei Mobile Services as the push provider.
  implementation 'com.webex.connect:webexconnect-hms:3.0.0'

  //In-App Messaging - Required to use In-App Messaging capabilities within your app.
  implementation 'com.webex.connect:webexconnect-inappmessaging:3.0.0'

}//It is recommended to use the latest version of each module.

dependencies {

  //FCM Module - Required to use Firebase Cloud Messaging as the push provider.
  implementation("com.webex.connect:webexconnect-fcm:3.0.0")

  //HMS Module - Required to use Huawei Mobile Services as the push provider.
  implementation("com.webex.connect:webexconnect-hms:3.0.0")

  //In-App Messaging - Required to use In-App Messaging capabilities within your app.
  implementation("com.webex.connect:webexconnect-inappmessaging:3.0.0")

} //It is recommended to use the latest version of each module.

Method 2: Manual Integration by Downloading Modules from the GitHub Repository. Please click on the link for detailed steps.

b. Configure Android Manifest

In your project, open AndroidManifest.xml and add the content below.

<!-- PERMISSIONS -->
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED"/>

c. Add IMIconnectConfig.properties file.

The IMIconnectConfig.properties file contains mandatory asset information as such the app id, client key and environment details and other necessary information, which is used to authenticate with the Webex Connect platform.

Download the file from the Webex Connect asset configuration page and place within your application asset directory.

Screenshot to download the `IMIconnectConfig.properties` file.

Screenshot to download the IMIconnectConfig.properties file.

d. Configure Proguard Rules

Add the below rule in proguard-rules.pro file.

📘

Note

If you use an obfuscation tool other than ProGuard, please refer to the tool providers documentation for configuring equivalent rules.

-dontwarn org.eclipse.jetty.** 
-dontwarn com.google.firebase.messaging.FirebaseMessaging 
-dontwarn javax.servlet.** 
-dontwarn org.slf4j.** 
  
# for sqlcipher 
-keep class net.sqlcipher.** { *; } 
-keep class net.sqlcipher.database.* { *; } 

# WorkManager 
-keep class * extends androidx.work.Worker 
-keep class * extends androidx.work.InputMerger 
-keep public class * extends androidx.work.ListenableWorker { 
  public <init>(...); 
} 
-keep class androidx.work.WorkerParameters

# For MQTT
-keep class org.eclipse.paho.client.mqttv3.** {*;}
-keep class org.eclipse.paho.android.service.** { *; }
-keepclasseswithmembers class org.eclipse.paho.** {*;}

-dontwarn org.eclipse.jetty.**
-dontwarn javax.servlet.**
-dontwarn org.slf4j.**
 
# for sqlcipher
-keep class net.sqlcipher.** { *; }
-keep class net.sqlcipher.database.* { *; }
 
# WorkManager
-keep class * extends androidx.work.Worker
-keep class * extends androidx.work.InputMerger
-keep public class * extends androidx.work.ListenableWorker {
  public <init>(...);
}
-keep class androidx.work.WorkerParameters
 
#Proguard rules for HMS
-ignorewarnings -keepattributes *Annotation*
-keepattributes Exceptions
-keepattributes InnerClasses
-keepattributes Signature
-keepattributes SourceFile,LineNumberTable
-keep class com.hianalytics.android.**{*;}
-keep class com.huawei.updatesdk.**{*;}
-keep class com.huawei.hms.**{*;}
 
# For MQTT
-keep class org.eclipse.paho.client.mqttv3.** {*;}
-keep class org.eclipse.paho.android.service.** { *; }
-keepclasseswithmembers class org.eclipse.paho.** {*;}

e. Initialize the SDK

The SDK uses Android App Startup to automatically register included modules and start the SDK. If you have disabled App Startup for your application, please follow the manual startup instructions provided within our Quick Start guide: Manual Startup Instructions.

f. Register a device

The user's device must be registered with the Webex Connect platform before other features can be used. To register a device, create a DeviceProfile instance and invoke the WebexConnect.register method.

A device profile must always have a unique device id and user id, if you do not supply a user id then the platform will assign one for you. Typically you will want to supply your own user id value that corresponds to a user within your backend systems.

val webexConnect: WebexConnect = WebexConnect.instance

// Initialize a device profile
val userId = "YOUR_USER_ID"
val deviceProfile = DeviceProfile(DeviceProfile.defaultDeviceId, userId)

// Register the device
webexConnect.register(deviceProfile) { jsonObject: JSONObject?, exception: WebexConnectException? ->
    if (exception != null) {
        Log.e("Registration", "Registration failed!", exception)
    } else {
        Log.d("Registration", "Registration succeeded!")
    }
}

WebexConnect webexConnect = WebexConnect.getInstance();

// Initialize a device profile
val userId = "YOUR_USER_ID";
val deviceProfile = new DeviceProfile(DeviceProfile.getDefaultDeviceId(), userId);

// Register the device
webexConnect.register(deviceProfile, (jsonObject, exception) -> {
    if (exception != null) {
        Log.e("Registration", "Registration failed!", exception);
    } else {
        Log.d("Registration", "Registration succeeded!");
    }
		return Unit.INSTANCE; 
});

SDK integration is now complete. To start using Push Messaging, please refer to our Push Messaging Guide and for In-App Messaging, please refer to our In-App Messaging Guide.

Updated about 1 month ago