Jump to: navigation, search

Android Sample

Updated in 8.5.203, 8.5.200

Download in Bitbutcket

In 8.5.202, the Android Sample moved to BitBucket, where you can download the code sample. The Android SDK used in this sample is available in Maven and includes the Javadoc JAR file that you can import in Android Studio. Once imported, the JAR file also provides automatic completion and documentation while using the Android Sample SDK.

Important
All installation and code details are provided in the BitBucket ReadMe where you can download the Android Sample.

In 8.5.114, the app was extended to support:

  • Chat V2 features, that are now available in the CHAT-V2 scenario:
    • File Transfer
    • Typing notifications
    • Typing preview
  • Mobile Push Notifications to Android devices using Firebase Cloud Messaging (FCM)
  • ApiGee integration


About Genesys Mobile Services Android Sample

The Genesys Mobile Services (GMS) Android sample illustrates how to implement an Android app that communicates with GMS and implements supported contact scenarios. It is primarily meant to be used by developers as a reference to build an Android app using the GMS Android SDK. This sample app can also be used to test an existing GMS deployment because the scenario parameters are configurable in the GMS Service Management UI.

In this repository, you can find the new Android Sample for GMS 8.5.2, using the GMS Android SDK library. To develop an application using GMS Android SDK, you need:

  • Android 4.0 (Ice Cream Sandwich) or higher
  • Android studio version 1.4 or higher
  • Latest GMS Android SDK library available in maven
Important

The Android SDK used in this sample includes the Javadoc JAR file that you can import in Android Studio. Once imported, the JAR file also provides automatic completion and documentation.

Prerequisites

To use the Android sample app, install, and start GMS version 8.5.201 and higher. Then, configure your services as follow:

  • Create your gmstester-callback service in the Configured Services panel of the Service Management UI.
    • Click create and select callback in the Service Template list.
    • Enter gmstester-callback for the Service Name and select sample in Common Default Configuration.
  • Deploy and configure the services that you want to use in the Configured Services panel of the Service Management UI or in the GMS Configuration for the Digital Channel APIs. For example, create the chat.customer-support service for CHAT-V2 in your GMS configuration.
  • Configure Firebase Cloud Messaging in your GMS Configuration. Edit the fcm section of the GMS configuration to provide your FCM API key.
  • Enable push notifications for Firebase Cloud Messaging in your GMS configuration:
Important

Restart GMS after configuring Firebase Cloud Messaging in the fcm and push sections.

Features and Scenarios

The Android Sample supports the Click to Call and Click to Chat scenarios, in addition to Callback Scenarios.

 Connect

Scenarios

 Scenarios
Scenario Description
VOICE-NOW-USERORIG (Voice Callback) The customer wants to contact the Contact Center immediately. The Callback service provides an access number and an access code (optional) that the customer can dial. Then, the customer’s inbound call is processed and routed to an agent.
VOICE-WAIT-USERORIG (Voice Callback) The customer wants to contact the Contact Center and agrees to wait for an agent. The Callback service notifies the mobile when an agent is ready, then provides an access number and an access code (optional) that the customer can dial. Then, the customer’s inbound call is processed and routed to an agent.
VOICE-NOW-USERTERM (Voice Callback) The customer requests an immediate callback, that is, as soon as the agent is available, the Contact Center dials a call.
VOICE-WAIT-USERTERM (Voice Callback) The customer requests a callback and agrees to wait for an agent. The Callback service notifies the mobile when an agent is ready and asks if the customer wants to be called back now or later.
VOICE-SCHEDULED-USERTERM (Voice Callback) The customer requests a callback at a specific date and time based on the Contact Center’s Office hours.
Chat V2 The customer starts a chat session using Chat V2 from Digital Channel. this
CUSTOM Enables you to test a simple service (not only the Callback service). For instance, you can test a stat service. The sample displays the result in a dialog box.
SIMPLE-SERVICE Enables you to test any of your callback services.

These scenarios are server-driven, which means that the server instructs the client with the actions needed to carry out the scenario. The client just needs to perform those actions and follow up the dialog with the server. Therefore, the client is flexible enough to support any scenario that is built using the same kind of actions. The following actions are supported:

  • DialNumber - The app makes a phone call.
  • ConfirmationDialog - The app displays a message.
  • DisplayMenu - The app displays a menu for the user to select an item that may affect how the scenario proceeds.
  • StartChat - The app starts a chat conversation. Asynchronous HTTP notifications (comet messages) are used for receiving chat server events.
Note Scenarios are detailed in the Running the sample section below.

Features

  • Push notifications through Firebase Cloud Messaging are supported. Delayed scenarios are supported by using push notifications only; the app will not poll the server to be notified about agent availability.
  • Request custom service
  • Server Response logs
  • Queue Statistics


Downloading the source

You can use either GIT or Sourcetree to download the source code.

GIT

  1. Download the latest version of GIT.
  2. Install GIT.
  3. Set up a variable that points to the GIT installation directory:

     GIT installation directory


  4. Add the GIT directory variable to the path variable:

     Adding GIT to the path


  5. Use the Windows Command Prompt to:
    1. Configure the necessary GIT global properties
    2. Clone the repository

       Cloning the repository

Sourcetree

  1. Install Sourcetree.
  2. Log into Sourcetree using your Atlassian ID.
  3. Open Sourcetree and click the Clone icon (1):

     Cloning the repository


  4. Enter the paths to the repository (https://username@bitbucket.org/genesysdevfoundry/gms-sample-android.git) (2) and the destination folder (3), then click the Clone button (4).
  5. You now see a screen like this:

     Results of cloning the repository


  6. Configure the necessary GIT global properties in Sourcetree by:
    1. Clicking Settings:

       Sourcetree Settings


    2. Navigating to the advanced tab and filling in the settings:

       Sourcetree Settings Advanced tab

Building the Sample

This sample uses the Gradle build system.

  1. First, download the samples by cloning this repository or downloading an archived snapshot.
  2. In Android Studio, use the “Import non-Android Studio project” or “Import Project” option. Next, select the root directory that you downloaded.
  3. If you get prompted for a Gradle configuration, accept the default settings. Alternatively, use the “gradlew build” command to build the project directly.

Here is the step-by-step user guide to open the Android sample in Android Studio.

Select “Open an existing Android Studio project”

 Open

Select the folder where the source was downloaded.

 Select

Android Studio loads, synchronizes, and builds the project.

 Loading

The sample opens.

 Build success

Clean the Android project and rebuild.

After cleaning, Android Studio builds the project automatically. If not, navigate to “Build > Rebuild Project” to force the rebuild.

 Clean

If the build is successful, click “Run” to start the sample.

 Run

The “Select deployment target” dialog opens and lists the available targets.

If an Android device is connected, it should be displayed in this list. Select the target or emulator where the sample should launch. As a result, the app installs in the chosen device.

 Target

Once the app is installed in the Device or Emulator, the app is launched.

You can also check the successful launch of the app in the terminal of Android Studio.

 Apk

Adding Firebase to the Android App/Project

This sample is delivered with a default google-services.json file. Before you run the sample, you must create your own file.

Prerequisites

  • A device running Android 4.0 (Ice Cream Sandwich) or newer
  • Google Play services 15.0.0 or higher

Adding Firebase to the Project

  1. Create a project in the Firebase Console
  2. Click “Add Firebase to your Android app” and follow the setup steps.
  3. When prompted, enter your app’s package name (for example, com.genesys.xxx.xxxx.xxxxx). Ensure to enter the exact package name that your app is using; you can set this parameter only when you add an app to your Firebase project.
  4. At the end of this process, download the provided google-services.json file. Note that you can download this file again at any time.
  5. Copy the ‘google-services.json’ file into your project’s module folder; typically, this file should be placed in the ‘app/’ folder.
Note If you have multiple build variants with different package names, ensure that you add each app to your project in the Firebase console.

Adding the GMS Android SDK

Edit the Gradle file (usually located in the ‘app/build.gradle’ folder) and add the GMS SDK version to the dependencies.

app/build.gradle
     
    dependencies {
        ....
        // Genesys GMS SDK module        
        implementation 'com.genesys.gms.android:sdk:<version>'

        ....
        // Important: The below mentioned plugin versions should be the same
        implementation 'com.google.android.gms:play-services-gcm:11.0.1'
        implementation 'com.google.firebase:firebase-messaging:11.0.1'
        ....
    }
    //This line is required at the end of file to avoid dependency collisions
    apply plugin: 'com.google.gms.google-services

You can add any additional application plugin dependency to the ‘dependencies’ section. the Firebase Version dependencies can be decided based on the Android application requirements. For more information about the Firebase version, visit https://firebase.google.com/support/release-notes/android.

Setup Android FCM Client

  1. Create a service which extends FirebaseMessagingService to perform any message handling beyond receiving notifications on apps in the background. This service receives data payload and notifications in foregrounded apps, sends upstream messages, and so on.
<service
    android:name=".FcmMessagingService">
    <intent-filter>
        <action android:name="com.google.firebase.MESSAGING_EVENT"></action>
    </intent-filter>
</service>
  1. Create a service that extends FirebaseInstanceIdService to handle the creation, rotation, and update of registration tokens. This service is required for sending events to specific devices or creating device groups.
<service
    android:name=".FcmInstanceIdService">
    <intent-filter>
        <action android:name="com.google.firebase.INSTANCE_ID_EVENT"/>
    </intent-filter>
</service>

Running the Sample

To run the Android sample, download the APK file and deploy it on your Android device. Alternatively, you can also compile the source code to make your own APK file by using the Android SDK. Using the sample is easy, as long as GMS is already deployed.

 Start up screen

The startup screen is a configuration screen. To enable push notifications to work, remember to:

  • Register a project in Google Cloud.
  • Enable the Firebase Cloud Messaging (FCM) for Android API.
  • In the app, fill the FCM sender id with your Google Cloud project number.

For more details, check the previous sections of this page or refer to Firebase Cloud Messaging - Getting Started.

Click or tap Scenario to display the list of available scenarios, then select one of them, for example, CHAT-V2.

Chat-V2

Click or tap Scenario to display the list of available scenarios, then select CHAT-V2.

 Start Chat

Fill the configuration options with the appropriate values of your GMS environment.

  • Enter your sample service name, for instance, gmstester-callback, and the service name used to implement your CHAT-V2 scenario, for example, customer-service.
  • Enter your API Key.
 Settings

Scroll down and ensure that push notifications are enabled. Then, connect the session by clicking the arrow icon in the top-right corner.

 Enable Notifications

The Chat session starts. You can now send and receive both messages and files. In addition, you are notified when the other participant is typing and you can leave the chat session by clicking the ‘X’ icon.

 Chat session started

VOICE-NOW-USERORIG

Click or tap Scenario to display the list of available scenarios, then select VOICE-NOW-USERORIG. The Callback service provides an access number and an access code (optional) that you can dial.

 Start Voice-Now

VOICE-NOW-USERTERM

Click or tap Scenario to display the list of available scenarios, then select VOICE-NOW-USERTERM. Then, connect. You will receive a call as soon as an agent is available.

 Select

VOICE-WAIT-USERORIG

Click or tap Scenario to display the list of available scenarios, then select VOICE-WAIT-USERORIG. Then, connect. The Callback service notifies the mobile when an agent is ready, then provides an access number and an access code (optional) that you can dial.

 Select
 Connect

VOICE-SCHEDULED-USERTERM

Select      

Log Section

To review in detail the communication between the client and the server, use the Log screen that you can open using the Show log option in the startup screen. You can also inspect the standard Android logging, by using the Android logcat tool, and obtain more details or logs on your computer screen.

TIP Filter with the GenesysService tag in order to see the client-server communication.

About the Code

The app is designed to be minimal to ensure that you can focus on the implementation of Mobile Services scenarios. It consists of:

  • MainActivity – Main activity which hosts the tab fragments and handles callback.
  • ConnectFragment - Displays the app configuration options and allows launching the Mobile Services scenarios.
    • SettingsFragment - Displays the service configuration options and interprets the server-driven actions.
    • QueueFragment – Holds the queue position and details in case the user is put on hold.
    • AboutDialogFragment – Displays the SDK version details.
  • ChatActivity – Implements all the key operations related to chat screens. The chat messages are handled by the following classes:
    • MessageHolder – Holds the content and the details of the message sent by both the user and the executive.
    • MessageListAdapter – Contains the list of messages sent during the chat session. This class handles and orders the messages which you can view entirely using the scroll option.
  • LogActivity - Displays logs.
  • Firebase Messaging Service:
    • FcmMessagingService - Performs any message handling beyond receiving notifications on apps in the background. To receive notifications in foregrounded apps, to receive data payload, to send upstream messages.
    • FcmInstanceIdService – Handles the creation, rotation, and update of registration tokens. This service is required for sending to specific devices or for creating device groups.
    • For more information regarding the latest FCM library and updates, refer the Android Documentation
  • The ChatClient class and some companion classes implement chat operations. These classes are meant to be reusable in your code. See the disclaimer below.

Disclaimer

THIS CODE IS PROVIDED BY GENESYS TELECOMMUNICATIONS LABORATORIES, INC. (“GENESYS”) “AS IS” WITHOUT ANY WARRANTY OF ANY KIND. GENESYS HEREBY DISCLAIMS ALL EXPRESS, IMPLIED, OR STATUTORY CONDITIONS, REPRESENTATIONS AND WARRANTIES WITH RESPECT TO THIS CODE (OR ANY PART THEREOF), INCLUDING, BUT NOT LIMITED TO, IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT. GENESYS AND ITS SUPPLIERS SHALL NOT BE LIABLE FOR ANY DAMAGE SUFFERED AS A RESULT OF USING THIS CODE. IN NO EVENT SHALL GENESYS AND ITS SUPPLIERS BE LIABLE FOR ANY DIRECT, INDIRECT, CONSEQUENTIAL, ECONOMIC, INCIDENTAL, OR SPECIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, ANY LOST REVENUES OR PROFITS).

License

Copyright 2018 Genesys

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Feedback

Comment on this article:

blog comments powered by Disqus
This page was last modified on 21 August 2018, at 08:45.