Android SDK Quickstart Guide

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.

Optional monitoring of device attributes allows change events to be reported back to the Webex Connect platform and values stored against the customer’s profile. These events may then be used to enrich user engagement through the triggering of rules and flows to send messages that may be more relevant to the user.

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

Prerequisites

The minimum requirements to use the Webex Connect SDK are:

Component

Requirement

Android Operating System

Android OS 4.1.x (API-Level 16) and higher

Software

Accounts

  • A valid Google account.
  • An active Webex Connect account.

OS Version Support

SDK Version

Min Supported OS

TLS Support

2.15.0 and higher

Android OS 4.2 (API 17) and higher

TLS 1.0 - Android OS 4.2.x - 4.4 (API 17 - 19)
TLS 1.1 / 1.2 - Android OS 5.0+ (API 20+)

2.12.0 and higher

Android OS 4.1.x (API 16) and higher.

TLS 1.0 - Android OS 4.1.x - 4.4 (API 16 - 19)
TLS 1.1 / 1.2 - Android OS 5.0+ (API 20+)

2.11.1 and lower

Android OS 4.0.x (API 15) and higher.

TLS 1.0 - Android OS 4.1.x - 4.4 (API 16 - 19)
TLS 1.1 / 1.2 - Android OS 5.0+ (API 20+)

Configuration Tasks

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

  1. Integrate Firebase
  2. Integrate HMS
  3. Configure a Mobile App Asset
  4. Import the SDK
  5. Code Integration

Integrate Firebase

The Webex Connect SDK leverages Firebase Cloud Messaging for its push capability. Please follow the official Firebase setup guide, which will take you through the process of configuring a Firebase project, adding Gradle dependencies and google-services.json to your Android Studio project.

🚧

Important!

If you use the Firebase Assistant, only follow steps 1 & 2, the SDK takes care of the rest, no additional code is required.

❗️

Firebase version support

Webex Connect SDK 2.10.0 supports Firebase versions 11.0.0 and higher.
Webex Connect SDK versions lower than 2.10.0 support Firebase versions 11.0.0 through 15.0.2.

Capture the Firebase Server Key

The Firebase Cloud Messaging server key allows Webex Connect to submit push notifications to your application. The following steps will provide directions for obtaining the key, please make a note of the key for use later in this guide.

  1. Open the Firebase Console
  2. Click the Firebase project to open it. (You created this in the previous section)
  3. Click the Settings icon, followed by Project Settings.
435435
  1. Click the Cloud Messaging tab.
  2. Make a note of the Server Key (This is needed within the next section)
14251425

Integrate HMS

📘

Note

If you do not need to support Huawei devices that do not have access to Google Play Services, you can safely skip this section and continue to Configure a Mobile App Asset.

Currently, we only support EMUI versions 10.x and above

Some Huawei devices do not have access to Google Play Services and therefore do not support Firebase. For these devices the Webex Connect SDK supports integration with Huawei Mobile Services (HMS). Please follow the official Huawei Integration guide to go through the process of configuring app information in AppGallery Connect, adding Gradle dependencies and agconnect-services.json to your Android Studio project.

Capture the Huawei App ID and App secret

Huawei Mobile Services (HMS) App ID and App secret allow Webex Connect to submit push notifications to your application. The following steps will guide you through enabling push and obtaining the App ID and App secret.

  1. Sign in to AppGallery Connect.
  2. Go to My projects and select the app you want to configure with Webex Connect.
  3. Enable Push Kit by following Huawei’s documentation.
613613
  1. Make a note of the App ID and App secret (This is needed within the next section).
612612

Configure a Mobile App Asset

Your application must be added to your Webex Connect tenant as an App Asset. The steps are different depending on which version of Webex Connect you use.

Webex Connect v5 tutorial: Create a mobile app asset in Webex Connect.

Webex Connect v4 tutorial: Create a mobile app asset in Webex Connect

📘

How to determine your Webex Connect version

To determine which version of Webex Connect you are using, please login to your tenant and expand the menu bar by clicking the double arrow at the bottom left of the screen, your version number will be displayed in the expanded view. If you do not have an expandable menu bar then you are using v4.

Import the SDK

This section provides the steps to add the Webex Connect SDK library (.aar) to your Android application.

📘

We do not currently support importing of the SDK via a dependency manager such as Maven central or JCenter.

  1. From the Webex Connect tenant portal menu, go to Tools > Download SDKs.
  2. Download the Android Core SDK.
  3. Unzip the SDK.
  4. Copy the IMIconnectCore.aar file to your app module libs folder.
  5. Open your Android Studio project.
  6. Add the following line within the dependencies section of your app build.gradle.
dependencies {
    //...
    implementation files('IMIconnectCore.aar')
    //...
}

Code Integration

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

a. Configure Android Gradle
b. Configure Android Manifest
c. Add IMIconnectConfig.properties file
d. Configure Proguard Rules
e. Initialize the SDK
f. Register a Device

a. Configure Android Gradle

In your project level build.gradle add the following entries:

For FCM:

buildscript { 
  repositories { 
    // ... 
    maven {url 'https://maven.google.com/'} 
  } 
  dependencies { 
    // ... 
    classpath 'com.google.gms:google-services:4.3.10’ } 
  } 
  allprojects { 
    repositories { 
      // ... 
      maven {url 'https://maven.google.com/'}
  }
}

For HMS :

buildscript { 
  repositories { 
    // ... // Configure the Maven repository address for the HMS Core SDK. 
    maven {url 'https://developer.huawei.com/repo/'} 
  } 
  dependencies { 
    // ... // For HMS // Add the AppGallery Connect plugin configuration. 
    classpath 'com.huawei.agconnect:agcp:1.4.2.300' } 
} 
allprojects { 
  repositories { 
    // ... // For HMS // Configure the Maven repository address for the HMS Core SDK. 
    maven {url 'https://developer.huawei.com/repo/'} 
  } 
}

For FCM:

In your app/build.gradle, add the following entries:

app/build.gradle
apply plugin: 'com.android.application' 
apply plugin: 'com.google.gms.google-services' 
android { 
  // ... 
} 
dependencies { 
  // ... 
  implementation files('IMIconnectCore.aar') 
  implementation "androidx.sqlite:sqlite:2.1.0" 
  implementation "androidx.work:work-runtime:2.7.0" 
  implementation "androidx.constraintlayout:constraintlayout:2.1.1" 
  implementation "com.squareup.picasso:picasso:2.5.2" 
  implementation "net.zetetic:android-database-sqlcipher:[email protected]" 
  implementation "org.eclipse.jetty:jetty-websocket:8.1.17.v20150415" 
  implementation "com.google.firebase:firebase-messaging:22.0.0" 
  implementation "com.google.android.gms:play-services-base:17.6.0" 
  implementation "com.google.android.gms:play-services-location:17.1.0" 
}

For HMS :

In your app/build.gradle, add the following entries:

app/build.gradle
apply plugin: 'com.android.application' 
apply plugin: 'com.huawei.agconnect' 
android { 
  // ... 
} 
dependencies { 
  // ... 
  implementation files('IMIconnectCore.aar') 
  implementation "androidx.sqlite:sqlite:2.1.0" 
  implementation "androidx.work:work-runtime:2.7.0" 
  implementation "androidx.constraintlayout:constraintlayout:2.1.1" 
  implementation "com.squareup.picasso:picasso:2.5.2" 
  implementation "net.zetetic:android-database-sqlcipher:[email protected]" 
  implementation "org.eclipse.jetty:jetty-websocket:8.1.17.v20150415" 
  // HMS dependency 
  implementation "com.huawei.hms:push:6.5.0.300" 
}

b. Configure Android Manifest

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

<!-- OPTIONAL Add the server domain from IMIconnect -->

<meta-data android:name="serverdomain" android:value="Your IMIconnect’s domain" />

For the SDK to function correctly, you must add the correct permissions to your app manifest. Some permissions are optional and need only be included if you use specific features, please refer to the comments below for further details.

<!-- PERMISSIONS -->
<!-- REQUIRED for connecting to imiconnect -->
<uses-permission android:name="android.permission.WAKE_LOCK"/>
<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED"/>
<!-- OPTIONAL add this permission if you wish to capture IMSI and IMEI details -->
<uses-permission android:name="android.permission.READ_PHONE_STATE"/>
<!-- OPTIONAL add this permission if you wish to monitor network attributes -->
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<!-- OPTIONAL add this permission if you wish to monitor account attributes such as email-->
<uses-permission android:name="android.permission.GET_ACCOUNTS"/>
<!-- OPTIONAL add this permission if you wish to monitor location and/or cell id changes -->
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<!-- OPTIONAL add this permission if you wish to monitor location changes to a fine degree of accuracy -->
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<!-- Replace YOUR_APPLICATION_CLASS_NAME with the name of your actual class that derives from the Application class. Do not worry if you do not already use an Application subclass in your project, we will create one later in this guide -->
<application
   android:name="YOUR_APPLICATION_CLASS_NAME"
   android:allowBackup="true"
   android:label="@string/app_name"
   android:theme="@style/AppTheme">
   <activity
       android:name="YOUR_ACTIVITY_NAME"
       android:label="@string/app_name">
       <intent-filter>
           <!-- OPTIONAL Include this section if you wish to use deeplinks -->
           <data
               android:host="command"
               android:scheme="@string/app_id"/>
           <category android:name="android.intent.category.DEFAULT"/>
           <category android:name="android.intent.category.BROWSABLE"/>
           <action android:name="android.intent.action.MAIN"/>
           <category android:name="android.intent.category.LAUNCHER"/>
       </intent-filter>
   </activity>
   <receiver
       android:name="com.imimobile.connect.core.messaging.ICMessagingReceiver"
       android:enabled="true"
       android:exported="false"
             android:permission="com.imimobile.connect.core.permission.PUSH_PERMISSION">
       <intent-filter>
           <action android:name="com.imimobile.connect.core.rtmevent"/>
           <action android:name="com.imimobile.connect.core.notification.click"/>
           <action android:name="com.imimobile.connect.core.intent.notification.RECEIVE"/>
       </intent-filter>
   </receiver>

</application>

c. Add IMIconnectConfig.properties file.

The IMIconnectConfig.properties file contains mandatory asset information as such the app id and client key 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.

For example, to download the IMIconnectConfig.properties file:

919919

Sample content:

# MANDATORY The App ID that is generated by IMIconnect for your application
appId=<APP_ID>
# MANDATORY The Client Key that is generated by IMIconnect for your application
clientKey=<CLIENT_KEY>
# OPTIONAL Add the IMIconnect's server environment, by default is AWS UK
environment=
# OPTIONAL Add the server domain to override zero-rating domain
serverDomain=
# OPTIONAL Add the allowUnencryptedDatabaseFallback to allow creating a default SQLite database when SQLcipher fails, by default is false.
allowUnencryptedDatabaseFallback=true

d. Configure Proguard Rules

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

📘

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

For FCM:

-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 HMS :

-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.**{*;}

e. Initialize the SDK


The SDK must be initialized before attempting to use any of its features. Initialization must occur from your Application.onCreate method, if your app does not have an Application class you must create one.

📘

Ensure you use the same name for your Application class as specified in your AndroidManifest.xml

public class MyApplication extends Application 
{
    @Override
    public void onCreate() 
    {
        super.onCreate();
      
        // Initialize the imiconnect SDK 
        try 
        {
            IMIconnect.startup(this);
        } catch (ICException e) 
        {
            e.printStackTrace();
        }
    }
}

📘

Registering Notification channel for Android O and above

Starting in Android 8.0 (API level 26), all notifications must be assigned to a channel or they will not be displayed.

Channels allow users greater control over their notifications. Users may disable specific channels or control the visual and auditory options for each channel directly from the Android system settings app. Users may also long-press a notification to change behaviors for the associated channel.

//Sample code to register Notification channel:

if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) 
{
  // Provide your channel name & description that will be visible to the user. These will need configuring in your strings.xml 
  String name = getString(R.string.channel_name);
  String description = getString(R.string.channel_description);

  // A channel registered with the id of ICConstants.DEFAULT_CHANNEL_ID is required as a minimum
  NotificationChannel channel = new NotificationChannel(ICConstants.DEFAULT_CHANNEL_ID, name, NotificationManager.IMPORTANCE_DEFAULT);
  
  channel.setDescription(description);
  
  // Register the channel with the system
  NotificationManager notificationManager = (NotificationManager) getSystemService(Context.NOTIFICATION_SERVICE);
  
  notificationManager.createNotificationChannel(channel);
}

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 an ICDeviceProfile instance and invoke the IMIconnect.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.

IMIconnect.register(new ICDeviceProfile(ICDeviceProfile.getDefaultDeviceId()), new ICRegistrationCallback()
{
   @Override
   public void onRegistrationComplete(final Bundle bundle, final ICException exception)
   {
     if (exception != null) 
     {
       Log.e("Registration", "Registration failed! Reason:" + exception.toString());
     } 
     else 
     {
       Log.d("Registration", "Registration succeeded!");
     }
   }
});
IMIconnect.register(new ICDeviceProfile(ICDeviceProfile.getDefaultDeviceId(),enteredUserId), new ICRegistrationCallback()
{
   @Override
   public void onRegistrationComplete(final Bundle bundle, final ICException exception)
   {
     if (exception != null) 
     {
       Log.e("Registration", "Registration failed! Reason:" + exception.toString());
     } 
     else 
     {
       Log.d("Registration", "Registration succeeded!");
     }
   }
});

📘

ICDeviceProfile provides a convenience device id implementation that is based on Secure.ANDROID_ID, but you are free to supply your own value instead if you wish.

Integration of the Webex Connect SDK is now complete and your application is ready to receive push notifications!