The Cisco Wireless Phone ships with the Cisco Web API app to support Web developers. The Cisco Web API app contains the JavaScript extensions necessary to support developer requirements, as detailed in this document. It allows developers to interface with external services and provide links to frequently used websites in addition to providing a way to configure the wireless phones to integrate with an XML application. The Web API provides:

• A widget to display a set of customer-defined URLs for applications and a special browser (WebView),

• A custom notification management tool, AlertView, that gives applications the ability to push data or a URL to the phone and have it displayed in the AlertView notification window.

• Provides the capability for applications to receive notifications of events or poll for status.

The Alertview notification window and the APP URLs widget ensure extended app availability for the Web API app.

By providing two separate activities for both pushed content and content the user has requested, content is separated, and the user does not lose the content that they asked for if pushed HTML content is sent to them:

• Pushed content is delivered to the user as a standard Android notification, which is displayed in the notification drawer. It is not assumed that all pushed content is more important than the current user activity. Therefore, only Critical priority pushed content will take over the user’s foreground activity and open the Alertview. Lower priority content is queued up and shown when the user selects the notification.

• User-initiated links in the App URLs launch when the user opens the widget box containing the App URLs. Once tapped, the shortcuts open applications within a browser.

Web applications running on Cisco Wireless Phones can be as simple as a list of contacts or as complex as a nurse call system. Cisco Wireless Phones support App URLs, where users can interact with Web pages as they would on a computer.

Development of a web application for the Cisco Wireless Phone generally follows these steps:

1. Planning. Defining the requirements of the application according to the facility’s needs.

2. Familiarization of the capabilities of the Cisco Wireless Phone.

3. Familiarization of the infrastructure requirements of the Cisco Wireless Phones – example: call control (telephony server), wireless LAN, etc. You will need to learn about the components of the entire system to implement your application. This knowledge is obtained through study of the Cisco Wireless Phone Deployment Guide and VIEW Program AP Guides.

4. Application development and configuration requirements development. From your research on the requirements of the infrastructure, you will develop both the application itself and configure the parameters that the wireless phones need to use in order to integrate with the application. The settings will become central to testing your application and ultimately will be deployed along with the application in test and customer environments.

5. The first phase of Application testing and debugging uses the Cisco Wireless Phone hardware, running your customized settings, and other components to mimic a telephony deployment: a simple wireless LAN environment and call server.

6. The second phase of application testing uses Cisco Wireless Phones are deployed in a customer representative wireless LAN test environment. This test setup is detailed in this guide. During this test, applications can be tested for capacity as well as robustness for phones moving on and off the wireless LAN (due to power cycles and out of range movement).

7. The third phase of application testing is done during deployment in a working environment.

8. Launch.

XHTML, or eXtensible HyperText Markup Language, is a family of XML markup languages that mirror or extend versions of the widely-used Hypertext Markup Language (HTML), the language in which web pages are written. XHTML is HTML 4.01 redesigned as XML.

You should ideally have experience working with HTML and XHTML programming or access to someone who has such experience to benefit from the information and discussion provided in this guide.

For more information, refer to the following online documents:

• W3C® HTML 4.0.1 Specification

• W3C HTML 5 Specification

• W3C XHTML 1.0 The Extensible HyperText Markup Language (Second Edition)

• W3C XHTML Basic 1.1 - Second Edition

• W3C XHTML 1.1 - Module-based XHTML - Second Edition

• W3C XHTML Tables Module – XHTML 2.0

Note	You can use whichever development languages or servers you choose, including JavaScript, PHP, Python®, Django®, Tomcat™ or Apache™. Use whichever tools you are most comfortable using, or those that are most supported by your IT department.

The Cisco App URLs are web application shortcuts that open in a pared-down browser with enhanced Javascript capabilities designed specifically for onboard applications.

A user accesses the App URLs by using programmed shortcuts that open the application. The web application shortcut widget box supports up to 10 icons for App URLs.

Long press the home screen to open the Widgets option. Scroll down to display the Web API widget option. Long press and drag the widget box to a home screen.

Install the Apps URLs widget box. The App URLs shortcuts display together in a widget box.

The App URLs supports true Cisco Wireless Phone applications with the following features:

• HTML 5 – without video support

• CSS 3.0 – allowing only a single transition at a time.

• SVG 1.1 (partial support)

• JavaScript / The Web API app is used by developers to interface with external services and provide links to frequently used websites.

• Web API allows you to configure the wireless phones to integrate with an XML application.DOM access

• XMLHttpRequest

• HTTP 1.1

• AJAX

The Cisco Alertview allows the user to see the top pushed Data or URL page (called an alert) in the queue that was sent to their Cisco Wireless Phone. It also sends notifications to the Android notification manager to alert the user of the number, and highest priority, of un-dismissed alerts.

It contains the following elements:

• Title bar showing the HTML <Title> * A button to dismiss the alert from the queue * A progress bar showing the web page loading progress

• Optionally shown softkeys (Btn1-4). See PolySoftKey.

Alertview example

Alertview that plays a sound. Force sound link opens a player

When a new push (Data or URL) is received by the phone, the Cisco Alertview does the following:

• Stores the push in the queue according to priority: Highest priority first and then ordered by received time - most recent first. See Using Push Requests.

Alertview notification example of multiple alerts

Once in the Alertview, a user can interact with your web application in the same manner as if they initiated the connection from a App URL shortcut. In fact, the User Agent of the App URLs and Alertview are identical.

The user can launch web applications in the Cisco App URLs widget box. When the user selects a web application by tapping its widget icon, the Cisco browser displays and the title bar shows a progress indicator as the page loads.

Handset behavior during App URLs functions

While the user is in a Cisco App URL page in the browser, if there is an event in the phone application that requires the user's attention (such as an incoming phone call), the incoming phone call activity displays automatically in the foreground and the Cisco App URL is placed on the recent activity list, just like on a consumer wireless phone. The user can return to the Cisco App URL by selecting it off the recent activity list, or by pressing the Back key.

Note	App URL display and other activities are not always interrupted. Not all events require the user’s attention to the display, for example, Push-to-talk audio traffic plays out the rear speaker without interrupting the current activity’s display.

The wireless phones are configured to reach and interact with the web application through their Web API configuration, which must be set accordingly. Configuration will include:

• The wireless phones must be configured to find the web application. At a minimum you will need to configure a URL location for the application itself and a label to display on the web app shortcut widget, which the user uses to initiate the application.

• The wireless phone must be configured to send required event notifications to the application server, minimally to notify the application of its IP address when it comes onto the wireless network.

• When applicable, the wireless phone must be configured to receive incoming pushes for the application to send alerts to the wireless phone.

• Other parameters can be required if your application requires telephony features such as personal alarms or emergency dial. The Cisco Wireless Phone Administration Guide will provide you will full details about Cisco application deployment.

Configuration information

You will need to set up your test phones with the parameters your web application requires to test your Application. While you can use a full-blown Enterprise Mobility Management (EMM) server to configure the Web API settings in your test phones, we recommend that you simply use the manual method for a small number of phones.

The Push URL mechanism is typically used to create an application-generated message, alarm or alert on the phone, to be displayed through the Cisco Alertview browser. This action, results in the Alertview receiving a URL address downloaded from the application web server.

The Push URL function supports the following two types of content URLs:

• XHTML content URL: The content will be displayed on Alertview. If it is not already open, it opens and displays the pushed message on Alertview.

• URI actions content URL: The URI actions specified in the file are executed on the wireless phone.

Instead of pushing a URL using the Push URL mechanism, you can push a small amount of HTML data directly from the application to the Cisco Alertview on the target wireless phone(s).

This feature does not allow for URI actions in the message, but URI actions can be defined as anchors within the Push Data mechanism. This tool is useful for broadcast messages especially to a large group of users, as the impact of a large number of browsers, i.e. Alertviews, requesting a URL from a web server simultaneously is avoided (as a Push URL would require).

The general message flow is summarized as follows:

Internal URIs are execution events that can be used for executing predefined actions in a specific scenario. It is similar to the manual execution of key presses. The wireless phone executes Internal URIs in the order they are received. The URIs must be defined in sequence and separated by a “;” (semicolon) character or newline character and the file should be served with content type application/x-com-Cisco-webx. This file can be sent to wireless phone using a URL push message.

Phone state polling enables you to fetch the following wireless phone configuration and call state information:

• Call Processing State

• Device Information

• Network Configuration

When the device receives any of these polling requests, it prepares the information in an XML format, and sends it to the configured polling URL or to the device that requested the Poll, depending on the state of the State Polling Response Method.

The wireless phone-initiated event notification is based on a state change in the wireless phone or a network connection event. This mechanism is used to integrate endpoint events into host application intelligence. When an Event Notification is triggered it prepares the information in XML format and sends it to the configured event notification URL.

Internal Uniform Resource Identifiers (URIs) provide the interface to execute predefined actions on the phone. These actions give you as a developer action to some internal functions that normally would take manual user action to perform.

There are two (2) ways to execute an internal URI action, as follows:

• The internal URIs can be sent as Data Push where content type must be: application/x-com-Cisco-webx

• If an XHTML file will include internal URI, they must be defined in (and executed from) anchor tags, in the href attribute (for example, <a href=tel:1234>Menu</a>). When the user selects the anchor, the action is processed and executed (in this case, dial phone number 1234).

Note	Internal URI actions contained in a file with content type “application/x-com-Ciscowebx” can be executed only through a URL push.

Use the following format when configuring the internal URIs:

where:

• ActionType is the type of action to execute (Tel, or Play)

• Action is the name/content of the action to be executed.

The supported internal URIs are described in the table shown next.

The LineIndex value is case insensitive.

If there are already 4 calls in progress the tel: URI request is ignored.

An error is logged in a log file if the file is too large to play.

Keep in mind that the following important notes regarding internal URIs:

Note	Registration 2 is commonly used for in-house call systems that use registration 2 to call an extension for alerts and other messages. For example, use tel:Reg2:2002 to place a call on registration 2 to extension 2002.

Note	A two-second pause is indicated by the “,” (comma). A one-second pause is indicated by a p character. The dual-tone multi-frequency (DTMF) is sent after the placed call is connected when specified after postd= as shown in the example below.

Example: Place a call to *50, and then wait two seconds before entering 44:

<html>
<head>
</head>
<body>
<a href="tel:*50;postd=,44">Push to Dial</a>
</body>
</html>

Note

Ensure you specify the file format extension of any audio files, e.g. alertsoundA.wav. The preferred supported file format is WAVE, G711 mu law or A law, 8KHz sampling rate, 8 bits per sample, monaural (aka mono). Audio software such as Audacity® can be used to create sound files of the correct format.

A push request is defined as an XML formatted request that you send to a phone to tell it to process the XML content. The phone may render the data, fetch a URL, or perform an action, depending on the content of the XML.

Note	See Push Settings for a list of parameters you can use to enable push requests in the wireless phone. Cisco Wireless Phone will convert PUSH request URLs to lower-case, so in effect the device will attempt to retrieve web pages and files using lower case.

Note	If a phone is in call and is sent a tel: push request that is with priority: high, normal or important), the phone accepts the push but does nothing. Only If the priority is critical will the call be placed immediately.

Event Notifications allow application programs insight into what wireless phones are doing, their status and their network information. Using a combination of them will allow an application to detect the power up of phones and the state of the phones.

For example, using a combination of events and phone state polls can allow an application to detect that a phone has registered with the call server (Line Registration Event) and then get the phone’s extension number, model # and firmware version (Device Info phone state poll).

The phone can be configured to send information to a specific URI if one of the following Event Notifications occurs:

• Personal Alarm Event

• Incoming Call Event

• Outgoing Call Event

• Offhook Event

• Onhook Event

• Call State Change Event

• Line Registration Event

• Line Unregistration Event

These events are XML data posted to a Web server by the phone.

Note	If you have configured a second registration for use by your application, you may use the <LineNumber> parameter to return information to differentiate the line.

Note	The header tag in the XML that identifies a Cisco Wireless Phone event notification <SpectralinkIPPhone> is not present in the event notification responses.

The phone can be configured to send the current state information to a specific URI or to the requestor upon receipt of an HTTP Phone State Poll request.

The following types of information can be sent:

• Receiving Call Line Information The line registration and call state will be sent upon receipt of an HTTP request to the call state handler (http://<Phone_IP>/polling/callstateHandler).

• Receiving Device Information Device specific information will be sent upon receipt of an HTTP request to the device handler (http://<Phone_IP>/polling/deviceHandler).

• Receiving Network Configuration Network specific information will be sent upon receipt of an HTTP request to the network handler (http://<Phone_IP>/polling/networkHandler).

Two HTTP transactions occur:

• The application sends an HTTP request to a particular handler in the phone.

• The Phone posts the state in XML format to a preconfigured Web server or to the sender of the request.

  Note	See State Polling for a list of parameters you can use to enable state polling in the wireless phone.

Phone state polling is used to determine if a given wireless phone is currently online. For example, you could send a phone state poll and wait for a response (5 sec). You can also determine of the wireless phone is in a call, or what code revision it has loaded.

The Cisco App URLs supports true Cisco Wireless Phone applications—nearly indistinguishable from a desktop application, provides immediate feedback and updates information without a deliberate refresh—with the following features:

• HTML 5 – no video

• CSS 3.0 – only one active transition / animation at a time.

• SVG 1.1

• JavaScript. Supports ECMA-262 with extensions.

• XMLHttpRequest

• HTTP 1.1

• AJAX

The App URLs is a fully compliant HTTP/1.1 user agent as described in RFC 2616. For more information, see http://www.ietf.org/rfc/rfc2616.txt?number=2616.

The App URLs supports:

• Cookies Cookies are stored in the flash file system; they are preserved when the phone reboots or is reconfigured.

• Refresh headers

• HTTP proxies

• HTTP proxy authentication The phone’s login credentials or the user’s name and password can be used to authenticate the user with the server.

• HTTPS by HTTP over TLS The App URLs will support the TLS protocol v1 only. It is not backward compatible with SSL v2 or SSL v3.

• Custom CA certificates

Note	For more information on CA certificates, see TBD.

The Cisco App URLs and Cisco Alertview provide access to phone-specific Document Object Model (DOM) JavaScript extensions. The DOM is created by the App URLs after parsing an XHTML file. JavaScript’s primary role in the App URLs is to modify properties of the DOM. The DOM is a collection of every object defined in the XHTML, for example, every button, every label, and every image. A web application can use JavaScript to modify DOM properties just like any other XHTML object.

Web API settings enable the wireless phone to display the label or name of your application in the web application shortcut widget point to the URL where the application resides.

There is a top-level Enable/Disable setting for the Web API. It must be enabled for the Web API features to function.

As with any software development project, there are a range of approaches you can follow. If you are new to developing Cisco Web applications, it may help to know a few tips to use and pitfalls to avoid before you begin. Use the following lists for guidance to the best practices to use when developing applications to run on the Cisco App URLs and Alertview.

The following points apply when developing applications for the Cisco App URLs and Alertview:

• Using the HTTP User Agent The application can use the HTTP user agent header information to determine a variety of details about the phone – such as the model – and deliver content tailored specifically for the phone’s and screen size and other capabilities. Applications running on phones that support the App URLs can also use JavaScript to detect the screen and/or window size.

• Supported Image Formats Cisco Wireless Phone supports GIF, PNG, JPG, and BMP image formats. Where image size is a concern, compressed JPG images are better for large images. For smaller images, the BMP image format provides better quality but lacks the compression benefit.

• Pushing Sensitive Data Avoid pushing security sensitive data direct to the phone. A URL push can be used to push a request to the phone to get the information from a HTTPS site, so the data will be encrypted. The URL push itself should not leak sensitive information.

• Using HTTPS for Event Notifications You may want to use HTTPS for event notifications and state polling because they contain sensitive information such as the phone MAC address, caller name and phone number.

• Implement a User Confirmation When including push notifications, be sure to implement a user confirmation response. Adding a confirmation response will ensure the user actually viewed the notification.

• Using Tel URI Your application should use TelUri API to make phone calls.

• Remove white space in code If concerned about Data Push content length (must be <2kb) you may process HTML, JavaScript, and CSS files to remove whitespace and shrink before delivery.

• Use lower case for PUSH requests Cisco Wireless Phone will convert PUSH request URLs to lower-case, so in effect the device will attempt to retrieve web-pages and files using lower-case.

With respect to the security of the REST API, the following should be noted:

• Authenticating remote control and monitoring The execution of each HTTP PUSH request requires MD5 digest authentication which can be further secured inside HTTPS. All pushed URLs are relative URLs with the root specified in the wireless phone’s configuration.

• Achieving confidentiality of executed content The phone’s HTTP client supports Transport Layer Security (TLS), so any data retrieved from the URL can be protected. Make sure of the confidentiality of all traffic past the initial push request by specifying a root URL that uses https.

• Event reporting The confidentiality of all events reported by the phone can be also be protected by TLS in the same way that push content is. Simply specify an HTTPS URL for the destination for Event Notifications.

• Data push When data push is enabled, content can be sent directly to the phone by the application server. The request will still be authenticated through HTTP digest, but all content will be in clear text on the wired network (wireless security will encrypt the traffic through the air). Cisco recommends that you only use unencrypted data push for broadcast type alerts that do not pose any confidentiality risks.

A controlled test environment uses a Cisco Wireless Phone working in a wireless LAN with a PC that is configured to function as a telephony server as well as, perhaps, providing all other server functions. At least one Cisco VIEW Certified AP is required. This setup will give you adequate verification of the workability of your application before it is deployed in a working facility.

A working system test is done in close coordination with an existing installation. The phone administrator needs the web API settings that you have customized for your application. Also, the application itself and any application server must be configured.