Polycom 3725-49106-001 User Manual

Web Application for Polycom® Phones

DEVELOPER GUIDE

UC Software 5.0.0 | September 2013 |3725-49106-001 Rev A

Polycom, Inc. 1

Copyright ©2013, Polycom, Inc. All rights reserved. No part of this document may be reproduced, translated into another language or format, or transmitted in any form or by any means, electronic or mechanical, for any purpose, without the express written permission of Polycom, Inc.

6001 America Center Drive San Jose, CA 95002 USA

Trademarks

Polycom®, the Polycom logo and the names and marks associated with Polycom products are trademarks and/or service marks of Polycom, Inc. and are registered and/or common law marks in the United States and various other countries. All other trademarks are property of their respective owners. No portion hereof may be reproduced or transmitted in any form or by any means, for any purpose other than the recipient's personal use, without the express written permission of Polycom.

End User License Agreement

By installing, copying, or otherwise using this product, you acknowledge that you have read, understand and agree to be bound by the terms and conditions of the End User License Agreement for this product.

Patent Information

The accompanying product may be protected by one or more U.S. and foreign patents and/or pending patent applications held by Polycom, Inc.

Open Source Software Used in this Product

This product may contain open source software. You may receive the open source software from Polycom up to three (3) years after the distribution date cost to Polycom of shipping

distributing the software to

the applicable product or software at a charge not greater than the

you.

To receive software information, as well as the

open source software code used in this product, contact Polycom by email at OpenSourceVideo@polycom.com.

Disclaimer

While Polycom uses reasonable efforts to include accurate and up-to-date information in this document, Polycom makes no warranties or representations as to its accuracy. Polycom assumes no liability or responsibility for any typographical or other errors or omissions in the content of this document.

Limitation of Liability

Polycom and/or its respective suppliers make no representations about the suitability of the information contained in

this document for any purpose. Information is provided “as is” without warranty of any kind and is subject to change

without notice. The entire risk arising out of its use remains with the recipient. In no event shall Polycom and/or its respective suppliers be liable for any direct, consequential, incidental, special, punitive or other damages whatsoever (including without limitation, damages for loss of business profits, business interruption, or loss of business information), even if Polycom has been advised of the possibility of such damages.

Customer Feedback

We are striving to improve our documentation quality and we appreciate your feedback. Email your opinions and comments to DocumentationFeedback@polycom.com.

Visit the Polycom Support Center for End User License Agreements, software downloads, product documents, product licenses, troubleshooting tips, service requests, and more.

Polycom, Inc. 2

Contents

About This Guide ...................................................................................................... 5

Conventions Used in This Guide .................................................................................................... 5

Information Elements ....................................................................................................................... 5

Typographic Conventions ............................................................................................................... 6

Writing Conventions ......................................................................................................................... 6

Coding Conventions ......................................................................................................................... 7

What’s in This Guide? ...................................................................................................................... 7

Getting Started ...................................................................................................... 8 1:

Recommended Software Tools ....................................................................................................... 8

Getting Help and Support Resources ............................................................................................. 8

Planning Your XML API Interface Requirements .......................................................................... 8

Strategies for Web Application Development ............................................................................... 9

Best Practices for Web Application Development ........................................................................... 9

Best Practices for Microbrowser Web Application Development ................................................... 10

Understanding Web Application Development on Polycom Phones ............. 12 2:

What is the Browser? ..................................................................................................................... 13

What is the Microbrowser? ............................................................................................................ 14

What is XHTML? ............................................................................................................................. 16

What Are the Differences Between the Microbrowser and Browser? ....................................... 16

What’s in the Software Development Kit? ................................................................................... 16

Launching the Polycom SDK ......................................................................................................... 17

What’s New in the Latest Polycom UC Software Updates? ....................................................... 17

Getting to Know the XML API Application Interface ........................................ 19 3:

Using Telephone Integration URIs ................................................................................................ 19

Using Push Requests ..................................................................................................................... 22

HTTP URL Push ............................................................................................................................ 23

HTML Data Push ............................................................................................................................ 25

Using Telephony Notification Events ........................................................................................... 27

Viewing an Incoming Call Event .................................................................................................... 29

Viewing an Outgoing Call Event .................................................................................................... 30

Viewing an Offhook Event .............................................................................................................. 30

Viewing an Onhook Event .............................................................................................................. 31

Viewing a Phone Lock Event ......................................................................................................... 31

Viewing a Phone Unlock Event ...................................................................................................... 32

Viewing a Call State Change Event ............................................................................................... 32

Viewing a Line Registration Event ................................................................................................. 33

Viewing a Line Unregistration Event .............................................................................................. 33

Viewing a User Login/Logout Event ............................................................................................... 34

Using Phone State Polling ............................................................................................................. 34

Polycom, Inc. 3

Receiving Call Line Information ..................................................................................................... 35

Receiving Device Information ........................................................................................................ 36

Receiving Network Configuration ................................................................................................... 37

Writing Your Web Application ................................ ........................................... 40

Developing Your Browser Application ......................................................................................... 40

Supporting HTTP ........................................................................................................................... 40

Launching the Browser from VVX Phones ..................................................................................... 41

Navigating and Form Editing on the Main Browser ....................................................................... 42

Viewing the Idle Browser................................................................................................................ 43

Using Browser JavaScript DOM Extensions .................................................................................. 44

Developing Microbrowser-Specific Applications ........................................................................ 47

Supporting XHTML Elements ........................................................................................................ 47

Supporting HTTP ........................................................................................................................... 62

Launching the Microbrowser from the Phone ................................................................................ 62

Navigating and Form Editing Behavior on the Main Browser ........................................................ 63

Viewing the Idle Browser................................................................................................................ 64

Sample Microbrowser Web Applications ....................................................................................... 64

Using Configuration Parameters ................................ ....................................... 73 5:

Configuring Web Application Parameters ................................................................................... 74

Configuring Push Request Parameters ........................................................................................ 75

Configuring Telephone Event Notification Parameters .............................................................. 76

Configuring Phone State Polling Parameters .............................................................................. 77

Configuring Programmable Soft Keys ......................................................................................... 77

Sample Configuration .................................................................................................................... 80

Getting Help ........................................................................................................ 83 6:

Polycom and Partner Resources .................................................................................................. 83

The Polycom Community............................................................................................................... 83

Troubleshooting ................................................................................................. 84 7:

Understanding Microbrowser Application Errors ........................................................................... 84

References .......................................................................................................... 86 8:

Additional Information ................................................................................................................... 86

Unsupported XHTML elements on the Microbrowser .................................................................... 86

JavaScript Examples for the Browser ............................................................................................ 90

Polycom, Inc. 4

Name

Icon

Note

The Note icon highlights information of interest or important information needed to be successful in accomplishing a procedure or to understand a concept.

Administrator Tip

The Administrator Tip icon highlights techniques, shortcuts, or productivity related tips.

Caution

The Caution icon highlights information you need to know to avoid a hazard that could potentially impact device performance, application functionality, or successful feature configuration.

Warning

The Warning icon highlights an action you must perform (or avoid) to prevent issues that may cause you to lose information or your configuration setup, and/or affect phone or network performance.

Web Info

The Web Info icon highlights supplementary information available online such as documents or downloads on support.polycom.com or other locations.

Timesaver

The Timesaver icon highlights a faster or alternative method for accomplishing a method or operation.

Power Tip

The Power Tip icon faster, alternative procedures for advanced administrators already familiar with the techniques being discussed.

Troubleshooting

The Troubleshooting icon highlights information that may help you solve a relevant problem or to refer you to other relevant troubleshooting resources.

Settings

The Settings icon highlights settings you may need to choose for a specific behavior, to enable a specific feature, or to access customization options.

About This Guide

This guide uses a number of conventions that help you to understand information and perform tasks.

Conventions Used in This Guide

This user guide contains terms, graphical elements, and a few typographic conventions. Familiarizing yourself with these terms, elements, and conventions will help you perform certain tasks.

Information Elements

The following icons are used to alert you to various types of important information in this guide

Icons Used in this Guide

Polycom, Inc. 5

Web Application for Polycom Phones UC Software 5.0.0

Convention

Description

Bold

Highlights interface items such as menus, soft keys, file names, and directories. Also used to represent menu selections and text entry to the phone.

Italics

Used to emphasize text, to show example values or inputs, and to show titles of reference documents available from the Polycom Support Web site and other reference sites.

Blue Text

Used for cross references to other sections within this document and for hyperlinks to external sites and documents.

Courier

Used for code fragments and parameter names.

Convention

Description

Indicates that you must enter information specific to your installation, phone, or network. For example, when you see <MACaddress>, enter your phone’s 12-digit MAC address. If you see <installed-directory>, enter the path to your installation directory.

Indicates that you need to select an item from a menu. For example, Settings > Basic indicates that you need to select Basic from the Settings menu.

parameter.*

Used for configuration parameters. If you see a parameter name in the form

parameter.* , the text is referring to all parameters beginning with parameter. See the section Reading the Feature Parameter Tables in

Polycom's UC Software 5.0.0 Administrators' Guide for examples.

Typographic Conventions

A few typographic conventions, listed next, are used in this guide to distinguish types of in-text information.

Typographic Conventions Used in This Guide

Writing Conventions

This guide also uses font styles to distinguish conditional information as listed in Table 3, as shown next.

Writing Conventions Used in This Guide

Polycom, Inc. 6

Web Application for Polycom Phones UC Software 5.0.0

<html>

Click on the link to engage the DND feature

<a href="Key:DoNotDisturb">DNDSettings</a>

</body> <softkey index="1" label="Back" action="SoftKey:Back"/>

</html>

Coding Conventions

Sample code is shown in this guide to assist you in writing your applications. All samples are presented in the following format.

Table 1: Sample Code

What’s in This Guide?

This developer guide is organized into eight chapters. The first chapter, Getting Started, introduces Polycom and Unified Communication solutions. The following chapters provide information on how to configure and deploy specific Polycom products and systems using the SDK and the latest UC software. The final chapters show you where to get help and other sources as well as outline known issues and workarounds.

Chapter 1: Getting Started gives you a quick overview of knowledge, hardware, and software you need before you begin. This chapter also provides frequently asked questions (FAQs) and resources for further help along with a checklist of things you can do before you begin writing your Web application

Chapter 2: Understanding Web Application Development on Polycom Phones gives you an overview of Web applications on Polycom phones.

Chapter 3: Getting to Know the XML API Application Interface provides information about the XML application information and gets you started with writing your Web application.

Chapter 4: Writing Your Web Application shows you how to write your Web application and provides examples.

Chapter 5: Using Configuration Parameters provides information on the phone’s configurable parameters and you can modify those parameters for your application.

Chapter 6: Getting Help shares links to support documents and websites from Polycom, Polycom partners, and other information that will assist you. You will also find links to the Polycom Community, which contains a number of discussion forums you can use to share ideas with your colleagues.

Chapter 7: Troubleshooting provides help when troubleshooting your Web application development. Chapter 8: References lists further information mentioned in this guide that can help you use the SDK

along with additional information to help you write your Web application.

Polycom, Inc. 7

Getting Started 1:

Getting Started provides you with information on helpful resources and recommended software tools that can aid you in Web application development on Polycom® phones with the Polycom UC software.

This Web Application Developer’s Guide provides you with information on how to install and use the

Polycom Software Development Kit (SDK). This guide shows you how to plan, create, and develop Web applications to run on Polycom phones using UC software.

This guide is designed to provide Web application creators with information for developing and deploying Web applications to Polycom phones. This guide is not intended for end users and does not provide userlevel information on how to use any specific Web applications. You need to be familiar with creating Web applications before reading this guide.

All Polycom phones run the Polycom® UC software. The software can be downloaded from the Polycom

Support Web site. Polycom also provides a simulation of different phone models with the Software

Development Kit (SDK). The Polycom Software Development Kit (SDK) can be downloaded from the

Applications page on the Polycom Web site.

Recommended Software Tools

Polycom recommends you use an XML editor – such as XML Notepad++ – to create and edit configuration files. Using an XML editor ensures that you create valid XML files. If the configuration files you create are not in the form of a valid XML structure, the files cannot load correctly on the phones.

For more complex applications, you need to use a fully Integrated Development Environment (IDE) like Eclipse or Microsoft Visual Studio. You can also use the Linux tool Curl to send arbitrary HTTP and XML content to a phone.

Getting Help and Support Resources

This developer guide includes a Getting Help section where you can find links to Polycom product, support, and partner sites. You can also find information about The Polycom Community, which provides access to discussion forums you can use to discuss hardware, software, and partner solution topics with your colleagues. To register with the Polycom Community, you need to create a Polycom online account.

The Polycom Community includes access to Polycom support personnel as well as user-generated hardware, software, and partner solutions topics. You can view top blog posts and participate in threads on any number of recent topics.

Planning Your XML API Interface Requirements

The XML API is supported in applications running on Polycom® SoundPoint® IP 321/331/335, 450, 550, 560, 650, and 670 desktop phones; SoundStation® IP 5000, 6000, and 7000 conference phones; SoundStation Duo conference phones; VVX® 500, 600, and 1500 business media phones; VVX® 300 and 400 desktop phones, and SoundStructure®.

Polycom, Inc. 8

Web Application for Polycom Phones UC Software 5.0.0

The XML API is designed to provide you with flexibility when developing Polycom phone applications

while securely integrating into the phone’s capabilities and functions. The XML API features are

supported by the Polycom browser and microbrowser, except where noted. You’ll find detailed descriptions and examples for the XML API features in Getting to Know the XML API

Application Interface.

Strategies for Web Application Development

Before you start to write your application, you need to define the purpose of your application. You need to decide what tasks the application is going to perform, how complex the application will be, and if the application will run on one or several phone models. You also need to take the varying screen sizes of the phones into account to determine a common size for your application.

Creating screen mockups of your application using a visualization tool, such as PowerPoint or Visio, can aid you in your development process and help others involved understand the overall application concept.

You need to determine your audience and understand their technological capabilities. Understanding who you are creating an application for helps you determine which features are most useful for your users.

If you are new to developing Polycom phone applications, knowing a few tips to use and pitfalls to avoid before you begin can aid you in the process. Use the following Best Practices lists for guidance when developing applications to run on the Polycom microbrowser and browser.

Best Practices for Web Application Development

Consider the following when developing applications for the browser or microbrowser:

 Using the HTTP User Agent You 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 screen size and other capabilities. You can also use JavaScript to detect the screen and/or window size for applications running on phones that support the browser.

 Supporting Image Formats A majority of phone models support both JPG and BMP image

formats, but keep in mind that phones that support the microbrowser do not support the JPGs format. When considering the size and quality of your application’s images, you need to know that compressed JPG images are better for large images, and BMP images have a better quality for smaller images but lack the compression benefit. For more information, see Image Tags.

 Scaling Images If an image is too large to fit a specific phone screen, ensure the server is able to

scale the image to fit the phone’s screen dimensions. Keep in mind that the phone’s performance suffers if the phone has to scale oversized images to fit the screen.

 Previewing Images To preview the appearance of your application’s images on the phone, set

your computer monitor color depth to 16-bit. This ensures that any images your application sends to the phone are prepared using a color depth that is equal to or lower than the phones color depth capabilities.

 Using Soft Keys If the phone model you are developing your application for supports soft keys or

shortcuts, add soft keys and shortcuts to your application to take advantage of their functionality. See Configuring Programmable Soft Keys. For more information, refer to the chapter Configuring

Soft Keys in the Polycom UC Software 5.0.0 Administrators' Guide.

Polycom, Inc. 9

Web Application for Polycom Phones UC Software 5.0.0

 Positioning Soft Keys Use a hard key press simulation to test your application, provided the

phone supports this function. When working with simulators, simulating key presses for call screen soft keys, such as EndCall and Transfer call controls, are not reliable. Depending on the phone’s configuration, you can adjust the soft key positions.

 Encrypting Configuration Files For security reasons, make sure you encrypt the configuration

files included in the application. You will need to generate a key, which you can download to the phone and use to encrypt configuration files. See Quick Tip 67442: When Encrypting Polycom UC

Software Configuration Files.

 Pushing Sensitive Data You can retrieve information from a HTTPS site by sending a request to

the phone with a URL push. The URL push itself does not leak sensitive information, but you need to ensure the data is encrypted and avoid pushing security sensitive data directly to the phone.

 Using HTTPS for Telephone Notification Events Use HTTPS for telephone notification events

and state polling to protect sensitive information, such as the phone MAC address, caller name, and phone number, which are contained in both.

 Implementing User Confirmation When including emergency push notifications, implement a

user confirmation response. In cases where the push and call happen simultaneously, the push message can be lost or hidden without the user knowing the event occurred. Add a confirmation response to ensure the user receives the notification along with the call.

 Using Tel URI To improve the performance of the phone with your application, you need to code

your application to use Tel Uri API to make calls instead of using digit key press simulation for dialing. For more information, see Using Telephone Integration URIs.

 Removing White Space in Code Review your HTML, JavaScript, and CSS files to remove

whitespace from the code before delivery.

 Setting the Idle Browser Refresh Cycle There are two ways you can refresh a browser: you can

set the mb.idleDisplay.refresh parameter to a non-zero value in seconds, or set the same parameter value to 0 and create a JavaScript code to do the refresh.

 Providing a Link for Text Input Although the idle browser is interactive, do not use the idle

browser for text input. If you want to implement text input into the idle browser, provide a link for another page to be displayed on the main Browser.

 Creating a Link Area Ensure the link areas are large enough for users to easily touch with their

finger. For example, avoid embedding a button inside the link area.

 Sharing the Idle Browser You can share the idle browser with multiple applications, so consider

what the page needs to do when not in use. For example, using iframe AJAX running in the background of a hidden browser can have an impact on the performance of the phone and make it run slower. Consider monitoring the OnUnload JS event. Use the PolyUri DOM extensions PolyUri.shownSig and PolyUri.hiddenSig to trigger behavior when your application is hidden or shown.

Best Practices for Microbrowser Web Application Development

Consider the following when developing Polycom phone applications specifically to support the capabilities of the microbrowser:

Polycom, Inc. 10

Web Application for Polycom Phones UC Software 5.0.0

 Minimizing Onscreen Information Make sure you do not include too much information at one

time on the screen of the idle browser. Because the idle browser has no scrolling capability, excessive information cannot be viewed and slows down the performance of the phone and wastes the bandwidth.

 Limiting Page Content If a page contains too much information, use multiple pages to avoid a

delay in displaying information or scrolling on the page. Keep in mind that the phone’s memory limitation hinders the amount of content that can be displayed on the screen.

 Avoiding Interactive Features for Idle Browser Pages Make sure to create an application that

is informational only. Because the idle browser is not interactive, avoid including user input elements like soft keys, buttons, or text input in your application.

 Providing Clear Instructions Make sure to include clear instructions for the user. For example, if

the Select soft key is enabled on an idle page, there needs to be an indication like ‘Press Select’ on the page. Do not assume the user will know to press the Select soft key.

 Stabilizing the Refresh Rate Make sure your application does not require a frequent refresh of

the idle browser. You can control how often your pages automatically refresh using JavaScript. A minimum 5 second delay is enforced by the phone.

 Controlling the Refresh Cycle You need to control the refresh cycle using your application’s

response HTTP to the server. Configure the refresh cycle in the configuration file to be as long as possible and only used as a recovery mechanism in case the HTTP connection fails due to a network problem.

 Providing Adequate Text Elements If a form contains text inputs and soft keys, provide a link

next to the text input so the cursor can be easily moved from the text box to display the designated soft keys.

 Limiting Cursor Navigations If a page includes multiple buttons or links, consider adding soft

keys as an additional input method for frequently used selections to avoid cursor navigations.

Polycom, Inc. 11

Phone

Browser is supported

Microbrowser is supported

VVX 300/310/400/410/500/600

Yes

VVX 1500

No (when running SIP 3.1.3 or earlier)

Yes (When running SIP 3.2.2 or later.)

Yes (when running SIP 3.1.3 or earlier)

No (When running SIP 3.2.2 or later.)

SoundPoint IP 321/331/335/450/ 550/560/650/670

Yes SoundStation IP 5000/6000/7000

Yes

SoundStation Duo2

Yes

SoundStructure

Note: SoundStructure Supports Features of XML API

SoundStructure doesn’t have a display screen, but it supports the InternalURI, Telephony Notifications, and Polling features of XML API.

Understanding Web Application 2:

Development on Polycom Phones

Polycom has two types of browser environments for Polycom phones running Polycom UC software: browser and microbrowser. Before you write your application, you need to explore both environments and choose the one that provides the best mapping to the phone models you want to write applications for. This chapter provides an overview of each browser environment and example applications that will run in each environment.

Table 2: Polycom Phones that Support the Browser and Microbrowser shows which phones support the

microbrowser and the total display area.

Table 2: Polycom Phones that Support the Browser and Microbrowser

When running SIP 3.1.3 or earlier.

Only supported on the SoundStation Duo while in SIP mode (as opposed to PSTN mode).

SoundStructure doesn’t have a display screen.

Web applications running on Polycom phones can be as simple as a list of contacts, or as complex as a

nurse call system. The phone’s screen size is one of the determining factors when developing

applications. Polycom phones support a full browser that enables you to interact with Web pages as you

Polycom, Inc. 12

Web Application for Polycom Phones UC Software 5.0.0

Admin Tip: Additional Tools to Create Applications

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

Web Info: Support for Polycom Phones

You can find documentation for all Polycom phones on the Polycom Support site. Choose your phone model for specific documentation. For more information, contact your Polycom distributer.

would on a computer, or a microbrowser that supports a limited set of XHTML tags and displays limited content. For a more information on which Polycom phones support a browser or a microbrowser, see

What is the Browser? and What is the Microbrowser?.

This chapter covers the following topics:

 What is the Browser?  What is the Microbrowser?  What is XHTML?  What’s the Difference Between the Microbrowser and Browser?  What’s in the Software Development Kit?

What is the Browser?

When a URL is configured on a phone or device, the browser enables you to browse and interact with Web pages like any browser. The browser supports Web-browsing functionality that is similar to Google Chrome on Android smartphones or Apple Safari on iPhones.

Polycom phone browsers are based on the open source WebKit platform. You can find the version of the WebKit platform on your phone in the user-agent string in network captures in the User-Agent HTTP header.

The browser supports Web 2.0 applications with the following features:

 XHTML 1.1  HTML 4.01 with partial support for HTML 5  CCS 2.1 with partial support for CCS 3.0  SVG 1.1 (partial support)  JavaScript  XML HTTP Request  DOM  HTTP 1.1  AJAX

Polycom, Inc. 13

Web Application for Polycom Phones UC Software 5.0.0

Phone

Total Screen Size (pixels)

Full Browser Screen Size (pixels)

Idle Browser Screen Size (pixels)

HTML5 Audio Tag Support

HTML5 Video Tag Support

When toolbar-autohide is enabled

When toolbar-autohide is disabled

VVX 600

480x272

480x252

480x217

480x190

Yes

VVX 500

320x 240

320x220

320 x 185

320 x 158

Yes

VVX 400

320x240

320x190

320x240

Yes

VVX 300

208x104

208x68

208x104

Yes

VVX 15001

800 x 480

800x455

800 x 395

610 x 360

The browser display is limited by the total display area available on each Polycom phone model. If you are creating an application for a specific Polycom phone model, consider the display area as a factor in the design of your Web application.

The following table shows the total screen size (in pixels) for each phone model and the audio and video tag support for each.

Table 3: Polycom Phone and Browser Window Sizes and HTML5 Audio and Video Tag support

When running SIP 3.2.2 or later.

What is the Microbrowser?

The microbrowser is what Polycom calls the smaller, limited-capability browser available on phones that feature smaller display screens. The microbrowser’s functions are similar to the browser available on phones with larger displays, but the microbrowser supports only a subset of the XHTML 1.0 features available to the browser. For example, it can connect to Web servers hosted on the Internet or intranet to display XHTML pages, but it does not have full Web browser functionality.

The XHTML pages displayed on the microbrowser contain static or dynamic information. This information is defined as follows:

 Static XHTML These pages are created using XHTML editors and are hosted by the Web server.

You can access these pages from the microbrowser using HTTP protocol. These XHTML pages are static because the information displayed is coded into the XHTML pages. These pages do not include information that continuously changes or contacts other services for updates.

Polycom, Inc. 14

Web Application for Polycom Phones UC Software 5.0.0

Note: No Support for JavaScript

The microbrowser does not support scripting such as JavaScript. All data actions entered into forms are processed by the server using POST or GET methods.

User Tip: Accessing Applications on the Microbrowser

You can launch the microbrowser on a SoundPoint IP or SoundStation IP phone by pressing the Applications key or access the microbrowser through the Menu key by selecting Applications.

Phone

Total Screen Size (pixels)

Microbrowser Screen Size (pixels)

SoundPoint IP 321/331/335

102 x 33

88 x 12

SoundPoint IP 450

256 x 116

171 x 72

SoundPoint IP 550/560/650/670

320 x 160

213 x 110

SoundStation IP 5000

240 x 68

240 X 32

SoundStation IP 6000

240 x 68

240 X 32

SoundStation IP 7000

255 x 128

255 x 79

SoundStation Duo1

240 x 68

240 X 32

VVX 15002

800 x 400

562 x 322

 Dynamic XHTML These pages involve dynamic information updates of XHTML pages by an

application hosted on the Web server. The application residing on the Web server retrieves information from an intranet or Internet data service provider like Yahoo, Exchange Server, Call Control Servers, or other enterprise servers.

When a Web or intranet URL is configured, the microbrowser downloads XHTML content into the phone’s memory and parses it to identify XHTML tags. The phone renders these tags onto the display screen, and the pages display according to the graphical capabilities and display size of the phone’s screen. Avoid creating complex Web pages to ensure the pages display correctly on all devices.

The following table shows the difference in screen dimensions of the browser and microbrowser on Polycom phones.

Table 4: Polycom SoundPoint IP, SoundStation IP, and VVX 1500 Screen and Microbrowser Window Sizes

Only supported on the SoundStation Duo while in SIP mode (as opposed to PSTN mode).

When running SIP 3.1.3 or earlier.

Polycom, Inc. 15

Web Application for Polycom Phones UC Software 5.0.0

Features

Microbrowser

Browser

XML API

programmable soft keys, telephone integration URIs, push requests, telephone notification events, phone state polling

telephone integration URIs, push requests, telephone notification events, phone state polling

Mark Up Languages

HTML 4.01 XHTML 1.0

XHTML 1.1. HTML 4.01 with partial support for HTML 5; CSS 2.1 with partial support for CSS 3.0; SVG 1.1 (partial support); JavaScript; XML HTTP Request; DOM; HTTP 1.1; AJAX

What is XHTML?

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 used to write Web pages. XHTML is HTML 4.01 redesigned as XML.

You need to have experience working with HTML and XHTML programming or access to someone who has experience in order to properly use and understand the information 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

What Are the Differences Between the Microbrowser and Browser?

The main difference between the microbrowser and the browser is that phones with larger screens are capable of displaying more complex Web content in the browser than phones using the microbrowser. Other comparisons between the microbrowser and the browser are shown in the following table:

Table 5: Microbrowser and Browser Comparison

What’s in the Software Development Kit?

The Polycom® Software Development Kit (SDK) provides you with a set of tools to help you develop XML API/XHTML applications. The SDK provides software-based simulators for certain VVX phones. Refer to the Software Development Kit page to learn more about which phone model simulators are supported in each of the available SDKs.

Polycom, Inc. 16

Web Application for Polycom Phones UC Software 5.0.0

Note: Differences Between Applications Running on Phones and the SDK

It is important to consider the difference between an application running on the computer-based simulator and the same application running on a real Polycom phone. Graphic animations and other processor or memory intensive functions could perform differently in either environment. There are other slight differences in the behavior of the simulators with respect to different versions of phone software.

Troubleshooting: Before Running the Simulator

The simulator uses port 80, and if any existing applications on your computer are using port 80, you either need to shut those applications down or configure a different port other than 80 for those applications.

The SDK installation file installs the following components on your computer:

 Phone Simulators  The SDK Quick Start Guide  An Apache Tomcat Web Server  The XML API Web Testing Tool

Launching the Polycom SDK

The Polycom SDK is a set of tools designed to assist you in developing XML API/XHTML applications for the VVX phones and provide a simulation of these phones. You need to download the SDK before creating your application. Using the SDK, you can test your application on the simulated phones and make any necessary adjustments before finalizing.

The Polycom SDK is available for download from the Polycom Support site. Refer to the SDK Quick Start Guide for more information on installing and using the SDK.

The SDK creates temporary files in the installed directory at startup. By default, Microsoft Windows Vista does not allow applications to modify/add files in certain directories due to security concerns.

To work around this issue:

1 Turn off the User Access Control (UAC) feature. 2 Install the SDK in another directory besides Program Files or Windows.

For example, during the installation process, enter c:\PolycomSDK as the install directory

What’s New in the Latest Polycom UC Software Updates?

If you’ve used previous versions of the Polycom SDK to develop applications, you may notice differences in the latest capabilities supported by the phones or changes to the simulators themselves. This section

Polycom, Inc. 17

Web Application for Polycom Phones UC Software 5.0.0

Note: Supporting Legacy Phone Models

Certain phone models, or legacy phones, are not supported in the Polycom UC Software 4.0.x release. For the appropriate software versions to use with these legacy phones, see the Polycom

UC Software/Polycom SIP Software Release Matrix. The software matrix indicates the level of

software support for each Polycom phone.

covers the range of functional improvements that were introduced with the latest UC software updates from 4.0.1 to 5.0.0.

The following features were introduced in UC software 4.0.1:

 SoundStation Duo conference phone  Flexible Line Key Assignment  SoundStructure VoIP Interface

 Support for the VVX 500 Business Media Phone

Refer to UC Software 4.0.1 Administrator’s Guide for additional information.

The following features were introduced in UC software 4.0.1 B:

 Support for SoundStructure

The following features were introduced with UC software 4.0.2:

 Browser has support for clearing the cookies and temporary Internet files from the cache.

The following features were introduced with UC software 4.0.4:

 Support for Tel URI Action on Microbrowser.  Added ability to dial '+' character by pressing '*' twice for international dialing.  Added ability to process DTMF entry during early media.

Refer to UC Software 4.0.4 Release Notes for additional information.

The following features were introduced in UC software 4.1.2:

 Support for the VVX 600 Business Media Phone.

Refer to UC Software 4.1.2 Release Notes for additional information.

The following features were introduced with UC software 4.1.4:

 Added support for VVX 300/310 and VVX 400/410 Business Media Phones.

Refer to UC Software 4.1.4 Release Notes for additional information.

The following features were introduced with UC Software 5.0.0:

 Support for HTML5 tag <input type="number"/>.  Added ability to delete characters with the onscreen keyboard on VVX 500 and 600 or delete soft

key onVVX-300 and 400.

 Added <audio> tag items and display of a volume bar when audio is playing.

Refer to UC Software 5.0.0 Administrators’ Guide for additional information.

Polycom, Inc. 18

Notes on API Security

The following should be noted about the XML API security:

 Authenticating remote control and monitoring The execution of each HTTP GET/POST

request requires an MD5 digest authentication. The execution of each HTTP PUSH request supports MD5 digest authentication as well as TLS and HTTPS. All pushed URLs are relative URLs with the root specified in the applications.cfg configuration file.

 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 You can protect the confidentiality of all events reported by the phone with

TLS similar to push content.

 Direct data push When direct data push is enabled—disabled by default— small amounts

of content (1KB) 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 network. Polycom recommends that you only use unencrypted data push for broadcast type alerts that do not pose any confidentiality risks.

Both apps.push.username and apps.push.password must be set for data push to be enabled.

Getting to Know the XML API 3:

Application Interface

The XML API provides you with flexibility in developing applications on Polycom phones while you securely integrate into the phone’s capabilities and functions. The XML API features are supported by the microbrowser and browser, except where noted.

This chapter covers the following topics:

 Using Telephone Integration URIs  Using Push Requests  Using Telephony Notification Events  Using Phone State Polling

Using Telephone Integration URIs

Internal Uniform Resource Identifiers (URIs) allow the interface to execute a set of predefined actions on the phone. These actions are similar to the manual execution of key presses on the phone.

Polycom, Inc. 19

Web Application for Polycom Phones UC Software 5.0.0

Note: Executing Internal URIs

Internal URI actions contained in a file with content type application/x-com-polycom-spipx can be executed only through a URL push.

Action Type

Action

Key

Line1 to Number of Lines supported by the Phone model., DialPad0 to DialPad9, Softkey1 to Softkey5, DialPadStar, DialPadPound, VolDown, VolUp, Headset, Handsfree, MicMute, Menu, Messages, Applications, Directories, Setup, ArrowUp, ArrowDown, ArrowLeft, ArrowRight, Backspace, DoNotDisturb, Select, Conference, Transfer, Redial, Hold, Status, Call List

The Key URIs send the key press event to the phone. The phone processes this event as if the button had been physically pressed.

SoftKey1

Back, Cancel, Exit, Home, Refresh, Reset, Submit, Fetch

The Soft Key URIs send the soft key press event to the phone. The phone processes this event as if the associated soft key had been physically pressed. These URIs function when the interactive microbrowser is on the screen.

The following are ways to execute an internal URI action:

 If the file sent to the phone contains only internal URI actions, which you can send as Data Push,

ensure the file content type is application/x-com-polycom-spipx. Each internal URI action must be separated by a newline and the execution is performed in order from the top down.

 If an XHTML file includes internal URI, you need to define and execute the file’s anchor tags in the

HREF attribute. For example, <a href=”Key:Setup”>Menu</a>. When you select the anchor, the action is processed and executed.

 Using the PolyUri() JavaScript function, apply one of the following soft key actions in anchor tags:

 SoftKey:Home  SoftKey:Back  SoftKey:Exit  SoftKey:Cancel  SoftKey:Refresh

See also Configuring Programmable Soft Keys.

Use the format ActionType:Action when configuring the internal URIs where:

 ActionType is a type of key or action to execute: Key, Soft key, Tel, or Play.  Action is the name of the action to be executed.

The supported internal URIs are described in the following table.

Table 6: Supported Internal URIs

Polycom, Inc. 20

Web Application for Polycom Phones UC Software 5.0.0

Action Type

Action

Tel23

Number;LineIndex;ext=<extension_no>;postd=<DTMF>

The Tel URI initiates a new call to the specified number on the specified line. The line number is optional. If the line number is not supplied, then the first available line is used. The digit map rules are followed (see Using the

Local Digit Map in the Polycom UC Software 5.0.0 Administrators’ Guide).

Play4

Play:<audiofile_path>

Download and play the audio file. The supported audio formats are G.711mu-law, G.711a-law, and Liner16. The <audiofile_path> is the relative path on the application server, relative to apps.push.serverRootURL. The supported maximum file size is determined by res.finder.sizeLimit. For G.711mu-law and G.711a-law files, sample rate must be 8ksps with a sample size of 8. This is supported on

all phones. For Liner16 files: Sample size must 16 for all sample rates. 16 bit PCM at 16 kHz sample rate. Sample rate of 16ksps is supported on SoundPoint IP 321/331/335, 450, 550, 560, 650, and 670, SoundStation IP

5000, 6000 and 7000, VVX 500, VVX600, VVX400, VVX410, VVX300, VVX310 and 1500. Sample rate of 32ksps and 48 ksps is supported on SoundStation IP 5000, 6000 and 7000, VVX 1500. Sample rate of 8ksps and 44.1 ksps is supported on VVX 500 and 1500.

Action

UpdateConfig

Update the phone’s configuration. This action works the same as selecting Menu > Settings > Basic > Update Configuration. Depending on which

configuration parameters have changed, the phone reboots.

1 The programmable soft key related URIs are not supported on the browser on the Polycom VVX phones. 2 The LineIndex value is case insensitive. The range of LineIndex is ‘Line1’ to ‘Line48’. 3 If the line corresponding to the LineIndex in the Tel action is busy, the existing call on that line is held and a call is

placed to the number specified in the Tel URI on that given line.

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

Keep in mind the following important notes regarding internal URIs:

 The action name and key type are case sensitive.  For non-XHTML content containing only internal URIs, the internal URIs are executed in the order

they appear in the file without any delay.

 If any URI is invalid and is in a file of only internal URIs, the entire file is rejected.

Polycom, Inc. 21

Web Application for Polycom Phones UC Software 5.0.0

<html>

Click on the link to engage the DND feature

<a href="Key:DoNotDisturb">DNDSettings</a>

</body>

</html>

<html>

<head>

</head>

<body>

</body>

</html>

Note: How to Indicate Pauses

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. You can use a combination of both the comma and letter “p” for any amount of time you want to use. These combinations can also be used in between the digits. For example, postd=pp1,12p8765.

 If any invalid URI is present in a XHTML file, the execution of that URI is ignored.

For example, Table 7 shows the code created for a link that behaves as if you pressed the Do Not Disturb key:

Table 7: Sample Code - Simulate Pressing of Do Not Disturb Key

For example, to place a call to *50, and then wait two seconds before entering 44:

Table 8: Sample Code – Pauses in Calls

Using Push Requests

A push request is an XML formatted request 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.

See also Configuring Push Request Parameters.

Polycom, Inc. 22

Web Application for Polycom Phones UC Software 5.0.0

Attribute

Permitted Values

priority1

Critical, Important, High, Normal

Sets the priority of the push, which determines how and when the URL is requested. For more information, refer to

Table 10: How Priority Affects URL Push Requests.

URI path2

String

Any relative URI (or relative URI path) on the configured application server.

Note: Defining PolycomIPPhone Tags

The <URL> tag must be defined under a <PolycomIPPhone> root tag. For example:

<URL priority=”Normal”>/examples/media.xhtml</URL>

</PolycomIPPhone>

Phone State

Priority

Description

Idle State Critical

The phone will display push request immediately.

High

The phone will display push request immediately.

HTTP URL Push

The HTTP URL push enables an application to push a URL to a phone to open its microbrowser or browser, as for example, an HTML Web page. The URL value sent within the push request is relative to the URL configured by the apps.push.serverRootURL configuration parameter. The pushed URL is appended to this root URL, and the microbrowser or browser attempts to open the pushed URL. This feature is asynchronous; and once the push request is received by the phone, it returns a 2xx or 4xx response immediately. There is no success/failure feedback for the push handling, and the pushing application does not know if the microbrowser or browser was able to open the pushed URL.

Use the following format when configuring the HTTP URL Push:

When pushing data to a phone, make sure to send the request to:

http://<Phone IP>/push

See Configuring Push Request Parameters. The URL push requests support the attributes listed in the following table.

Table 9: URL Push Request Attributes

If attribute is absent, Normal is used.

Currently multiple URIs in a single push request are not supported.

The following table describes the results of using a specific priority when the phone is in different states.

Table 10: How Priority Affects URL Push Requests

Polycom, Inc. 23

Web Application for Polycom Phones UC Software 5.0.0

Phone State

Priority

Description

Important

The phone will display push request immediately.

Normal

The phone will display push request immediately.

Non-Idle State

Critical

The phone will display push request immediately.

High

The phone will display push request immediately, but it will appear after critical push requests.

The phone will check whether the last processed message is of the same or a higher priority. If it is the same or a higher priority, then the phone will wait until the phone returns to the idle state before displaying the message.

Important

The phone will display push request immediately, but it will appear after critical and high push requests.

Normal

The phone will ignore push request in push queue until the phone returns to the idle state.

<URL priority=”Normal”>/examples/media.xhtml</URL>

</PolycomIPPhone>

Keep in mind the following important notes regarding HTTP URI push:

 The URI that the phone fetches is a concatenation of the apps.push.serverRootURL and the

URI sent in the Push URL message.

 By default, a Back soft key is placed on the graphic display.  The Back soft key will not appear when mb.main.autoBackKey is set to 0 or when custom soft

keys are shown using JavaScript; otherwise, it will appear.

 Push requests are displayed as first-in-first-out except for when noted in Table 66: Supported

Actions in <softkey> Tag.

 All HTTP requests are challenged through HTTP Digest Authentication.  If the phone cannot fetch the content from the pushed URI, the request is ignored.

For example, if apps.push.serverRootURL is configured in a phone to be http://1.2.3.4/apps, to push the display of a XHTML page media.xhtml, you would send the following XHTML:

Table 11: XHTML Code

where media.xhtml is hosted by a Web server at http://1.2.3.4/apps/examples/media.xhtml.

Polycom, Inc. 24

Web Application for Polycom Phones UC Software 5.0.0

Attribute

Permitted Values

priority1

Critical, Important, High, Normal

Sets the priority of the push, which determines how and when the URL is requested. For more information on how priority affects HTML push requests, see the following table.

text2

Text in HTML format

Any text.

Note: Where Tags Are Defined

The <Data> tag must be defined under a <PolycomIPPhone> root tag. For example:

<Data priority=”Important”> <h1> Fire Drill at 2pm </h1> Please exit and congregate at your appropriate location outside </Data>

</PolycomIPPhone>

Phone State

Priority

Description

Idle State

Critical

The phone will display push request immediately.

High

The phone will display push request immediately.

Important

The phone will display push request immediately.

Normal

The phone will display push request immediately.

Non-Idle State

Critical

The phone will display push request immediately.

HTML Data Push

The data push enables you to send XHTML page content directly to a phone without the overhead of the phone having to fetch the XHTML.

Use the following format when sending the HTML Data Push:

When pushing data to a phone, make sure to send the request to:

http://<Phone IP>/push

The attributes listed in the following table are supported by HTML push requests.

Table 12: HTML Push Requests

If attribute is absent, Normal is used.

The maximum content length for push request is 2KB.

The following table describes the results of using a specific priority.

Table 13: How Priority Affects HTML Push Requests

Polycom, Inc. 25

Web Application for Polycom Phones UC Software 5.0.0

Phone State

Priority

Description

High

The phone will display push request immediately, but it will appear after critical push requests.

Important

The phone will display push request immediately, but it will appear after critical and high push requests.

Normal

The phone will ignore push request in push queue until the phone returns to the idle state.

<h1> Fire Drill at 2pm </h1>

Please exit and congregate at your appropriate location outside

</Data>

</PolycomIPPhone>

Key:Line1

Key:DialPad0

Key:DialPad1

</Data>

</PolycomIPPhone>

For example, to push the display of an important message:

Table 14: To Push the Display of an Important Message

For example, to push the URIs for execution:

The content type must be application/x-com-polycom-spipx.

Table 15: To Push the URIs for Execution

Polycom, Inc. 26

Web Application for Polycom Phones UC Software 5.0.0

Attribute

Permitted Values

Phone IP

IP address

IP address of the phone. For example, 172.24.128.160.

MACAddress

MAC Address

MAC address of the phone. For example, 0004f214b8e7.

CallingPartyName

name

The name displayed in the phone's From label in the screen. If the line is registered and the call is initiated from that line, then the registered line display name of the calling party is shown. If the line is not registered and the call is initiated from that line, the IP address of the calling party is shown. For example, sip:172.24.128.160.

Using Telephony Notification Events

Telephony events allow application programs insight into how the phones operate. Using a combination of telephony events enables an application to detect the starting of the phones, the signing on of users, and the ongoing condition of the phones.

For example using a combination of events can enable an application to:

 Detect when a phone has registered through the Line Registration Event.  Detect when multiple users log into a different phones each day through the Line Registration

Event + User Login Event.

You can configure the phone to send information to a specific URI if one of the following telephony notification events occurs:

 Viewing an Incoming Call Event  Viewing an Outgoing Call Event  Viewing an Offhook Event  Viewing an Onhook Event  Viewing a Phone Lock Event  Viewing a Phone Unlock Event  Viewing a Call State Change Event  Viewing a Line Registration Event  Viewing a Line Unregistration Event  Viewing a User Login/Logout Event

These events are XML data posted to a Web server by the phone. For details on how to configure these events, see Configuring Telephone Event Notification Parameters. The following table contains the attributes for all telephony notification events.

Table 16: Telephony Notification Attributes

Polycom, Inc. 27

Web Application for Polycom Phones UC Software 5.0.0

Attribute

Permitted Values

CallingPartyNumber

number

The number displayed on the phone. If the line is registered and the call is initiated from that line, the registered line number of the calling party is shown. If the line is not registered and the call is initiated using IP address from that line, the IP address of the calling party is shown.

CalledPartyName

name

The name displayed in the phone's To label in the screen. If the call is received by a registered line, the registered line display name of the called party is shown. If the call is received on a non-registered line, the IP address of the called party is shown.

CalledPartyNumber

number

The number displayed on the phone. If the call is received by a registered line, the registered line number of the called party is shown. If the call is received on a non- registered line, the IP address of the called party is shown.

CalledPartyDirNum

number

If the line is registered, the value is the registered line number. If the line is not registered, the value is the IP address of the called party.

CallingPartyName

name

If the line is registered, the value is the registered line display name. If the line is not registered, the value is the IP address of the calling party.

CallingPartyDirNum

number

If the line is registered, the value is the registered line number. If the line is not registered, the value is the IP address of the calling party.

CallDuration

number, seconds

The duration of the call.

Call State

Outgoing call states: Dialtone, Setup, RingBack Incoming call states: Offering Outgoing/Incoming call states: Connected,

CallConference, CallHold, CallHeld, CallConfHold, CallConfHeld

Shared line states: CallRemoteActive

The call state.

CallType

Incoming, Outgoing

The call type.

TimeStamp

time

The date and time the event occurred on the phone. For example, 2008-07-11T13:19:53-08:00.

LineNumber

number

Line that is registered. For example, ‘1’.

Polycom, Inc. 28

+ 64 hidden pages