Developer Network

Here is the video of the UCCX Config API Developer Training

https://cisco.webex.com/ciscosales/lsr.php?AT=pb&SP=MC&rID=65968487&rKey=8194f60c7ffd4b23

Finesse gadgets can be hosted on your own web server or on the Finesse server itself.

To host gadgets on your own web server, you host the gadget just as you would any web site. You could use IIS, Apache, etc. That is up to you.

You specify in the Finesse gadget layout (see the Finesse Administration guide) the location for files on the web server where you place the gadget files. For example for the CUIC sample gadget, on Apache web server I place the files in C:\Program Files (x86)\Apache Software Foundation\Apache2.2\htdocs\ so that when I access the web site at http://<host>/CUIC.xml I can retrieve the xml file. The web server knows to retrieve any include files (CUIC.js and CUIC.css and finesse.js and jquery-1.5.min.js) since they are listed in CUIC.xml.

When you upload the CUIC gadget files (either to your own web server or to Finesse) be sure to also upload the required include files as listed in the Readme.txt:

Finesse.js and jquery-1.5.min.js

These files are in the finesse javascript library. Download the file finesse_javascript_library_and_samples_9.1.1.zip on the Tools section of Finesse Documentation page. Unzip the file and use the files that are in \Finesse_9.1.1\samples\GadgetSamples


Then in the gadget layout on the desktop layout tab of the Finesse Administrative desktop, you put the address of the xml file

<gadget>http:<host>/<directory>/CUIC.xml</gadget>

Where <host> is the ip address of the server you have installed to host the gadget files, and <directory> is the location that you would browse to in order to retrieve the files from the web server.

For example my web server is at 10.201.64.72 and the gadget files are in the CUICGadget subdirectory of my htdocs directory,
So my gadget layout has <gadget>http://10.201.64.72/CUICGadget/CUIC.xml</gadget>

You modify the gadget layout using the Administrative login and going to the Desktop Layout tab. See the Finesse Administration GuideFinesse Administration guide for more details.

When Finesse retrieves the gadget xml file, the web server automatically returns any imbedded javascript and css files assuming they are in the same location with the .xml file. These files are spelled out in the CUIC.xml file as files to include.

Alternately you can host the gadget on the Finesse server if you have Finesse 9.1(x) or later . To do this, see the section "Third Party Gadgets" in the Finesse Developer Guide. You would then upload the gadget files to the Finesse server and specify in the Administrative Desktop Layout the following:

<gadget>http://localhost/3rdpartygadget/files/CUIC.xml</gadget>

Where localhost is the Finesse server. The 3rdpartygadget/files directory is where you upload the gadgets using the 3rdpartygadget account and password.

bMost of the information you need is in this Finesse Developer Center and there is a detailed presentation for Finesse Developers here https://communities.cisco.com/docs/DOC-28452

You can explore the Finesse Developer Center http://developer.cisco.com/web/finesseand if you can’t find what you need, let us know.

For an overview of Finesse and creating Finesse gadgets http://developer.cisco.com/web/finesse/technical-overview

You will need a Finesse and UCCE lab. Getting started with that is defined here http://developer.cisco.com/web/finesse/getting-started-guide

Once you are able to work with the Finesse Agent desktop and the Cisco supplied gadgets, and are ready to develop your own gadgets, start with the Finesse Javascript Library by downloading it from the tools folder on the documentation page http://developer.cisco.com/web/finesse/documentation

The Finesse 9.1(1) version of the finesse javascript library is in finesse_javascript_library_and_samples_9.1.1.zip
Unzip the file and you will see a Gadget and Non-Gadget sample directories.
Copy the files from Finesse_9.1.1\samples\GadgetSamples to your 3rd party web server where you will be hosting your custom gadgets. (You can have the Finesse server host your gadgets by following the directions in Chapter 10 of the Finesse Developer Guide)

Then you will need to add the sample gadget to your Finesse Layout XML. For information on modifying the default layout see the Finesse Developer ppt here https://communities.cisco.com/docs/DOC-28452 and the Finesse Administration Guide
For the finesse gadget sample you will be adding something like
<gadget>http://<IPaddress>/3rdpartygadget/files/SampleGadget.xml</gadget>

There is a presentation on creating a Finesse gadget here https://communities.cisco.com/docs/DOC-28452

Next try downloading and installing the other sample gadgets in the Sample Gadgets directory. You might start with Screenpop.zip
You can see a video on how to modify the screenpop gadget to screenpop your own url here: http://developer.cisco.com/web/finesse/videos

That should get you started. If you have any questions you can post them here or in a new forum thread.

Last time I talked about some of the additional features that the Cisco Unified Communications Manager brought to table in regards to the DX650. I did however leave out a crucial ability of the CUCM, which is pushing applications to the DX650. This is a feature that the system administrator of the CUCM would be able to perform. So, let's take a look at creating this IP Phone Service by going to your CUCM Administration page under Device Settings > Phone Services.



Above is what you will see when you try and create your IP Phone Services. There is a few required fields that you need. Let's go through each of these fields.

Service Name/ASCII Service Name: This value must be the package name of the Android Application that you are trying to install. This is required in order for the service to work.
Service URL: The location of the Android APK you are installing.
Service Category: Set this to Android APK.
Service Type: Set this to Standard IP Phone Service.
Service Version: This is the version code that is specified in the Android Manifest. If leave this blank it will automatically re-download the application every time the configuration is updated. Assuming you don't want this to happen just fill this in with the version code. If the version code you specify is different from the Android Manifest it will not update the application. If you update the version with a different value and update the subscription it will update the application. Please note this is the version code, not the version name.

At the bottom you see that there is a Parameters section, this is used to send additional information to the application. For instance, you want to name the phone. Let's take a look at how we would pass this name to our device.



Above you can see the parameter that we created with the name of Name. The default value or the value that will be stored with the key of Name is DX650. This parameter will be installed on your device as a shared preference. With this in mind the application can just grab the value out of the shared preference. Below is a small code snippet that would do just that. If you need more information on Shared Preferences head on over to the Android Developer Site. Knowing about this Parameter section when writing your Android Application could come in handy.



Once the service is setup, all you have to do is go to the Device page and subscribe the device to the service you created. This will then in turn push the application to your device.

Designing Applications For the DX650

Writing applications for the DX650 is no different than writing applications for any other Android device. With that being said, a very common questions about our device and I’m sure other devices as well, is “Why doesn’t my app work on your device?.” My standard answer is “Because you did something wrong!”

Obviously, that’s not a fair thing to say without more information. To understand the problem with modern devices, you have to take a brief look at the history of Android.

To gain access to Google applications like the Play store a device must meet rigorous standards as defined at http://source.android.com/compatibility/. The Android Compatibility Definition Document (CDD) and Compatibility Test Suite are used to define the standards and test that a device meets the standard.

To fully understand why some applications don’t work on some devices, you have to look at the history of the CDD. For example, in version 1.6 (Éclair) the rule regarding the Camera is:

Device implementations MUST include a camera

Not much wiggle room there because in a formal specification, MUST means just that, it’s required and non negotiable.

If you fast forward to the version 4.0 (Ice Cream Sandwich) CDD, it says:

Device implementations SHOULD include a rear-facing camera and May include a front-facing camera.

This is obviously a big change in the definition (a good one in my opinion), and it adds some complexity that developers need to deal with. Why would the definition change? In the beginning all Android devices were pretty much the same. As time passed there was a desire to have devices in different sizes and shapes, and it really didn’t make sense to force them all to the same characteristics.

Another quick example. In Android 1.6 compatible devices were required to have an Accelerometer, Compass and GPS. In 4.0, the requirements are that a device must correctly report the sensors that it has and that the sensors must report accurate and genuine data (no fake sensors allowed), but there is no requirement that a device has any sensors at all.

As Android changed, one thing they tried to do was preserve backward compatibility, so in many cases, an old app will work on a new device. There are exceptions of course, for example, if an application was written when cameras were required, that application will likely have problems on a modern device with no camera at all.

So what’s the best approach to dealing with the fact that many different devices exists. I’ll suggest three methods

• Google Play Filtering
• Runtime Detection
• Just Deal With It (my favorite)

Google Play Filtering

All devices that access Google Play must passed the compatibility tests which means they must accurately report their features. For example: these are the features reported by a DX650

feature:reqGlEsVersion=0x20000
feature:android.hardware.bluetooth
feature:android.hardware.camera.front
feature:android.hardware.faketouch
feature:android.hardware.location
feature:android.hardware.location.network
feature:android.hardware.microphone
feature:android.hardware.screen.landscape
feature:android.hardware.touchscreen
feature:android.hardware.touchscreen.multitouch
feature:android.hardware.touchscreen.multitouch.distinct
feature:android.hardware.usb.accessory
feature:android.hardware.usb.host
feature:android.hardware.wifi
feature:android.software.live_wallpaper

In the Manifest for your application, you can if you want ,define various device requirements such as screen size, the presence of a rear camera or other device specific features.

Google play looks at both the device requirement in the application Manifest and the features reported by the device and filters (removes) any applications that require a feature that doesn’t exist on a specific device. If you’ve ever wondered why applications are available for some devices and not others, now you know.

You can get a full explanation of how this works here: http://developer.android.com/google/play/filters.html

This filtering feature is great for applications that are deployed from Google Play, but as an application developer you may want to have the ability to deploy your application via other means, or you may simply want more devices to have access to your application.

Runtime Detection

Many problems can be solved before they exist by simply writing good code. As devices have change Android has done a great job of adding the ability to determine device characteristics at runtime rather than just assuming that the device had a specific feature. Take the Camera for example. Prior to Android version 2.3 the Camera had a simple “open()” method that returned the “default” camera which must be a back-facing camera. In Android 2.3, the front cameras were first allowed and all cameras became optional, new APIs were added to allow your application to get the number of cameras, the type of camera (front, back) and a new “open(int cameraId)” method that allows you to specify which camera you want to use.

In my opinion, no modern application should ever use the old Camera.open() method, but instead should use the modern APIs to detect the cameras and open the specific camera that it needs.

For a good example of detecting capabilities at runtime, check out James Catalano’s blog on using the from camera. These same techniques can be used for other device dependent features.

Dealing with different screen sizes and resolutions is another complex subject. The Android Developer site has several great guides include “Supporting Multiple Screens” and “Designing for Multiple Screens.


Just Deal With It

Detecting capabilities at runtime and writing your code to adjust accordingly is a good first step, but you can do more. Rather than just failing gracefully if a feature doesn’t exist, I think you can go one step further by writing your application to adapt, or “deal with” whatever capabilities are present on a specific device.

For example, the DX650 doesn’t have a GPS. Is this a problem? Not really. GPS is a very low power signal and most GPS radios don’t work well or even at all indoors. Also, a DX650 isn’t a mobile device, so exact location isn’t necessarily as important as it would be for other devices.

But what if your application needs to know your location when recording some event, or because you want to show businesses nearby.

Not a problem. One of the Google services is a Wi-Fi based location technology, known as “Course Location” on Android. Remember above when I said a device “must correctly report the sensors that it has”. The DX650 reports Course location, but not Fine (GPS) location. Applications can be written to use Fine Location, Course Location, or even both depending on what is available at runtime.

Cisco DX650 Device specifics

Now that you understand the potential problems and several solutions, it’s worth mentioning a few of specific characteristics of the DX650.

Screen Size: 1024x600
Screen Density: 160dpi also known as mdpi
Orientation: Landscape
Cameras: 1 Front Facing Camera
Sensors: None
Location: Course/Network based only

Conclusion

Taking full advantage of the tools and APIs available in Android is key to writing stable, well-behaved applications that work on a variety of devices, now and in the future. Even if you are only targeting a single device, like the DX650, I encourage you employ the best practices described above.