This specification defines an Application Programming Interface (API) for that provides lauching application in device.

This document represents the early consensus of the group on the scope and features of the proposed Application launcher API. Issues and editors note in the document highlight some of the points on which the group is still working and would particularly like to get feedback.

Introduction

W3C application launcher API provides interface for invoking the native applications such as messaging, telephony and installed applications. An installed native application can be launched based on scheme of the standard URI Generic Syntax [[!URI]]. The following example URIs illustrate several URI schemes for application laucher API.

http(s) : launching installed browser in the device [[!URI]]
http://www.w3.org/2009/dap/
mailto: lauching email application [[!URI]][RFC6068]
mailto:chan@w3.org, mailto:chan@w3.org?subject=test
tel: launching telephony application [[!URI]][RFC3966]
tel:+82-123-456-789
sms: launching SMS application [RFC5724]
sms:+82-123-456-789

Need to clarification. What is the minimum supported URI scheme and their native applications? mmsto, sip, file, and etc .

Use Cases and Requirements

Use Cases

Use Case 1: Launching the device browser (URI base Application Launching using http URI scheme)

A Web application needs to launch the device browser in order to provide a "full browser experience" for a website. Without the ability to explicitly launch the browser (through a URI scheme e.g. http:// or https://), all the Web application can do is to load the website content directly, if it can access it. This may prevent the intended user experience, e.g. the launching of a browser session with a content storefront link.

Use Case 2: Launching a dialer for a phone call (URI base Application Launching using other URI scheme)

Web applications, such as one in a social network service, would provide personal contact information such as phone numbers or email addresses. The user of the Web application gives a call to his/her friends by clicking a phone number in the contact information. Using an appropriate application launcher API, a web application invokes a device dialer with a standardized URI(e.g. tel:, sms:). The device dialer would be invoked with the given phone number so that the user can call his/her friend by just clicking a call button.

Use Case 3: Launching an application to open document files (URI base Application Launching with MIME type)

A web application would open document files(e.g. doc, pdf format) with a specific viewer or text editor. The web application invokes a native application to open a file using an application launcher API.

Use Case 4: Setting default application (Management functionality for Application Launching)

An application is designed to work best with a particular browser, e.g. some Web resources to be invoked through the browser need a feature set supported by the particular browser. The application can find out what browsers are installed on the device, and set the default browser to use for links that launch the external browser, e.g. anchor elements with trget "_blank" or window.open methods.

Use Case 5: Using a web application as a home launcher (External Application Launching)

Using an application launcher API, a web application would launch a native application without the need to specifying URI or mime type. Once a web application fetches applications installed on a device, it displays the list of applications. User can start an application just by clicking the icon of the application.

Use Case 6: Find/retrieve applications on the device (Management functionality for Application Launching)

Using an application launcher API, a web application would check whether a specific application is installed on the device.

Requirements

Need to develop the more requirements based on Use Cases.

The following requirements for application launcher API have been expressed. The requirements for this set of interfaces may moved in the Device API Requirements document [[DAP-REQS]].

Usage Examples

The following code extracts illustrate how to work with a application launcher API in the device:

Further examples are required to give better understanding concerning the overall functions of the application launcher API.

Define the success and error callback, and get the default application for application/pdf mime type, change the default application of it, and launch application.

// Define the success callback for the getDefaultApplication method.
function appSuccessCB(applications) {
  //do something with resulting applications
  for(var i in application) alert(navigator.service.applicationManager.isDefaultApplication(application[i]);
  //...
}

// Define the success callback for the setDefaultApplication method
function defaultAppSuccessCB(response) {
   alert( "The default application has successfully changed");
}

// Define the error callback.
function appErrorCB(response) {
   alert( "The following error: " +  response.code + ", occurred launching an application");
}

// Get the default application for the application/pdf mime type.
navigator.service.applicationManager.getDefaultApplication('application/pdf', appSuccessCB, appErrorCB);

// Change the default application for the application/pdf mime type.
navigator.service.applicationManager.setDefaultApplication('application/pdf', defaultAppSuccessCB, appErrorCB);

// Define the data object
var data = navigator.service.applicationManager.createData(uri:'http://www.w3.org/2009/dap/applauncher.pdf', 
                                                           mimeType:'application/pdf'}); 

// launch an application
navigator.service.applicationLauncher.launchApplication(data, appErrorCB);

Security and Privacy Considerations

This section is under development.

The API defined in this specification can be used to launch the application on device. This information can potentially compromise user privacy and a conforming implementation of this specification MUST provide a mechanism that protects the user's privacy and this mechanism should ensure that such operations MUST be authenticated.

Privacy considerations for implementers of Application Launcher API

A conforming implementation of this specification MUST provide a mechanism that protects the user's privacy and this mechanism SHOULD ensure that privacy information is not revealed without user's informed consent.

API Description

This section is under development.

ApplicationLauncher interface

The ApplicationLauncher interface offers methods concerned with launching applications on the device.

PendingOp launchApplication ()
Launches a native application installed in the local device with URI and mime type of the data.
Data data
An object containing the URI and mime type of the data
optional AppErrorCB? appErrorCB
Function to call when the asynchronous operation fails
PendingOp launchApplication ()
Launches a native application installed in the local device with the information of the application.
Application application
An object containing the least information of the native application
optional AppErrorCB? appErrorCB
Function to call when the asynchronous operation fails

Data interface

The Data interface contains URI and mime type of the data.

attribute DOMString uri
URI of the data
attribute DOMString mimeType
Mime type of the data

Application interface

The Application interface captures various information of the application which is installed on the device.

readonly attribute DOMString id
The unique id to specify the application
attribute DOMString name
The name of the application.
attribute DOMString description
The description of the application
attribute DOMString location
The path that application installed
attribute DOMString executableFile
The executable file of the application
attribute DOMString installedDate
The date application installed
attribute DOMString recentUsedDate
The date application recently used
attribute unsigned short applicationStatus
The current application state(e.g., running, background, off)
attribute unsigned short networkAccessibility
The network accessibility of the application
const unsigned short RUNNING = 0;
The application is running on the device
const unsigned short BACKGROUND = 1;
The application is running on the background of the device
const unsigned short OFF = 2;
The application is not running on the device
const unsigned short NOT_USING_NETWORK = 0;
The application doesn't have authority to access device's network
const unsigned short WIFI = 1;
The application is able to access network only for WIFI network
const unsigned short 3G = 2;
The application is able to access network only for 3G network
const unsigned short WIFI_AND_3G = 3;
The application is able to access network for bot WIFI and 3G network

ApplicationManager interface

setDefaultApplication can cause security problems since the method can affect the configuration of the OS to be changed.

The ApplicationManager interface offers methods that manages application in the device.

Data createData ()
Creates data object that contains URI and mime type of the target data.
DOMString uri
URI of the target data
DOMString mimeType
Mime type of the target data
PendingOp getInstalledApplications ()
Returns an array of applications containing information of the installed applications on the device. (applications that have somehow been registered in the platform).
AppSuccessCB appSuccessCB
Uses the response object to retrieve the array of strings with the fully qualified path to the application in the terminal file system
optional AppErrorCB? appErrorCB
Function called when an error occurs, the input parameter is an Error object with the error code giving information about the type of error that occurred
PendingOp findApplications ()
Returns an array of applications that is able to execute given mime type.
DOMString mimeType
Mime type of the data
AppSuccessCB appSuccessCB
Function to call when the asynchronous operation completes
optional AppErrorCB? appErrorCB
Function to call when the asynchronous operation fails
boolean isDefaultApplication ()
Returns true when the application is default application for a given mime type.
DOMString mimeType
Mime type of the data
Application application
The object contains information of application
PendingOp getDefaultApplication ()
Retrieves default application for specific mime type.
AppSuccessCB appSuccessCB
Function to call when the asynchronous operation completes
optional AppErrorCB? appErrorCB
Function to call when the asynchronous operation fails
PendingOp setDefaultApplication ()
Sets application as a default application for specific mime type which is parameter.
DOMString mimeType
Mime type of the data
Application application
The object contains information of application
optional AppErrorCB? appErrorCB
Function to call when the asynchronous operation fails

AppSuccessCB interface

The AppSuccessCB lists the applications in the device.

void onSuccess ()
Success callback that is used in the asynchronous operation to retrieve a list of applications.
Application[] applications
An array containing the list of the information of applications

AppErrorCB interface

void onError ()
AppErrorCB errorCB
The Application Launcher API related error object of an unsuccessful asynchronous operation.

AppError interface

Add Application Launcher API specific error codes...

The AppError interface encapsulates all errors in the manipulation of Application objects in the Application Launcher API.

const unsigned short UNKNOWN_ERROR = 0
An unknown error occurred.
const unsigned short INVALID_ARGUMENT_ERROR = 1
An invalid parameter was provided when the requested method was invoked.
const unsigned short NOT_FOUND_ERROR = 2
If no response information can be provided from the requested method.
const unsigned short TIMEOUT_ERROR = 3
The requested method timed out before it could be completed.
const unsigned short IO_ERROR = 5
An error occurred in communication with the underlying implementation that meant the requested method could not complete.
const unsigned short NOT_SUPPORTED_ERROR = 6
The requested method is not supported by the current implementation.
const unsigned short PERMISSION_DENIED_ERROR = 20
Access to the requested method was denied at the implementation or by the user.
const unsigned short PENDING_OPERATION_ERROR = 4
If the user agent is currently waiting for a callback on a current launchApplication(), getInstalledApplications(), findApplications(), getDefaultApplication(), or setDefaultApplication() operation, as defined in this specification.
readonly attribute unsigned short code
An error code assigned by an implementation when an error has occurred in Application Launcher API processing.

Related documents

The API described in this document took inspiration from the following documents:

Features for Future Consideration

This is a list of features that have been discussed with respect to this version of the API but for which it has been decided that if they are included it will be in a future revision.

Acknowledgements

...