< Back to Package Overview

Basic Integration of Desk Phone Services into an Application

Overview

This article describes the combined steps needed to integrate the most basic uses of desk phone services into your application. Many of these steps will have further information in other articles.

Application Integration Steps

Add desk phone services to the build

Add the needed lines to your build.gradle or equivalent build file to import the desk phone services library, in addition to the communications package. Build and Runtime Environment

Define receivers for platform intents in Android manifest file

Add the following block to the AndroidManifest.xml file for your application project, inside the <application> element:

If your application needs to work in a non-Aura environment without support for emergency calls (e.g. IP Office), you must also include the following action inside the <intent-filter> element:

See Settings and Configuration and Credentials Management for the details of why this is required.

Add code to initialize desk phone services

As part of your application's initialization, you need to do the following:

1. Initialize the communications package and get a Client object instance for it.

2. Optional: Pass a log listener into the deskphone services library, to redirect logs from the library into the logging solution used by your application.

   You can pass in an object implementing the LogListener interface to the DeskPhoneServiceLibrary#setLogListener() method. This is the same logging interface as used by the Client Services package, so you can use the same log listener instance for both if you wish.

   If you do not pass a log listener instance into the library, its logs will go to Android's logcat facility.

3. Initialize desk phone services and get a service object reference

   Once only, you get a reference to the DeskPhoneService object by calling the initialize() static method in the DeskPhoneServiceLibrary class.

       DeskPhoneService deskPhoneService = DeskPhoneServiceLibrary.initialize(
               applicationContext, myDeskPhoneEventListener, client, null);
   

   You should do this after the Client is successfully created, and before creating any User objects. Note that on Vantage you should wait for a login event before creating the User.

Implement the listener interface for events from desk phone services

The second parameter passed to initialize() is your application's implementation of the DeskPhoneEventListener interface. This is used by desk phone services to report events back to your application. You'll need to add logic here for the following cases:

• configuration change events (onConfigurationChange()) This is called when the Vantage platform has configuration data for your application. You will need to parse that data and handle any resulting changes. See Settings and Configuration for details.
• login events (onLogin()) This is called when the Vantage platform requests that your application login to the network. You will need to trigger the communications package to create the User object here. See Credentials Management for details.
• handset on-hook and off-hook events (onHook() and offHook()) This is called whenever an attached handset goes on or off hook. You'll need to update your call state and provide support for off-hook dialing here. See Off-Hook Dialing for details.
• initialization complete event (onInitialised()) This is called when the desk phone services package has finished its initialization. You do not need to have any code here, but it's provided in case your application has anything it needs to do when that initialization is complete.

Pausing Configuration Changes Temporarily

The Vantage platform can send configuration change events to your application at any time. But there may be times in your application flow when configuration changes would be disruptive, e.g. if the user is on an active call.

You can use the DeskPhoneService reference to temporarily suppress configuration change events. Call pauseConfigurationEvents() at the beginning and then resumeConfigurationEvents() at the end to avoid getting configuration change events during that interval.

Refresh desk phone services if the Client changes

Due to limitations in the communications package, it is sometimes necessary to call shutdown() on a Client to change certain configuration items or re-initialize the entire package, resulting in a new Client instance. If you do so, you must pass the new Client instance to desk phone services, using the service object instance you got from initialization.

    deskPhoneService.updateCommunicationsClient(newClient);

Further Extension and Customization

There are two optional additional items that you may wish to customize as part of initializing desk phone services.

• See Audio Device Management for details of how to use the default audio device handler logic.
• See Routing Communications Package Events to Vantage Platform for details of how to customize which events from the network are automatically handled by desk phone services, for certain advanced uses.

Sample Code

Avaya Vantage™ Basic sample application source code is available from Avaya Vantage DevConnect Portal