Introduction

This is the Reference Documentation for the Unity Web API (version 1.0). This is a full API reference, a quickstart guide is also available

Requesting the Unity API object

In order to use the Unity API it is required to first request the API object:

method external.getUnityObject(String version);
external.getUnityObject method

The external.getUnityObject method returns the Unity API object.

Arguments:

Returns:

Throws:

Example code:

var Unity = external.getUnityObject("1.0");
The Unity API Object

We begin with the toplevel Unity object. If you know which interface you are interested in, jump ahead.

dictionary UnityInitParameters {
   String name;
   String iconUrl;
   Callback onInit;

   optional String homepage;
   optional String domain;
}
interface Unity {
   method init (UnityInitParameters initializationParameters);

   method addAction (String actionName, Callback onActionInvoked);
   method removeAction (String actionName);
   method removeActions ();
	
   UnityNotificationInterface Notification;
   UnityMessagingIndicatorInterface MessagingIndicator;
   UnityMediaPlayerInterface MediaPlayer;
   UnityLauncherInterface Launcher;
}
UnityInitParameters dictionary

UnityInitParameters is a specification of a dictionary containing Unity initialization data. Three parameters are required:

There are two optional parameters:

Unity.init method

In order to initialize the interface, a client must call the Unity.init method. Usage of any methods in the Unity interface besides init before initialization occurs will produce no result. It is guaranteed this will not produce an error.

Arguments:

Throws:

Example code:

function unityReady () {
   // Make use of the Unity API
}
Unity.init ({name: "Fooapp",
             iconUrl: "http://www.ubuntu.com/icon.png",
             onInit: unityReady});      
Unity.addAction method

The Unity.addAction method may be used to expose a hierarchy of application actions to the Unity HUD.

Arguments:

Throws:

Example code:

Unity.addAction("/File/Send to/Contact", onSendToContact);
Unity.removeAction method

The Unity.removeAction method is used to remove a previously added action by path.

Arguments:

Throws:

Example code:

Unity.removeAction("/File/Send to/Contact");
Unity.removeActions method

The Unity.removeActions method removes all previously added actions.

Example code:

Unity.removeActions();
The Unity.Notification interface

The Unity.Notification interface is used for displaying transient notifications to the user. Such notifications should not be urgent, or require user input.

interface UnityNotificationInterface {
   method showNotification (String summary, String body, optional String iconUrl);
}      
Notification.showNotification method

The showNotification method presents a single notification to the user.

Arguments:

Throws:

Example code:

Unity.Notification.showNotification("Just so you know", "This is a notification!");     
The Unity.MessagingIndicator interface

The Unity.MessagingIndicator interface has three main components:

dictionary UnityIndicatorProperties {
   Integer count;
   Date time;
   String iconURI;
   Callback callback;
}
interface UnityMessagingIndicatorInterface {
   method showIndicator (String name, optional UnityIndicatorProperties indicatorProperties);
   method clearIndicator (String name);
   method clearIndicators ();

   method addAction (String name, Callback onActionInvoked);
   method removeAction (String name);
   method removeActions (String name);

   method onPresenceChanged (Callback onPresenceChanged);
   readonly attribute String presence;
}      
UnityIndicatorProperties dictionary

UnityIndicatorProperties is a specification of Indicator properties to be passed to MessagingIndicator.showIndicator method. Note, the indicatorProperties parameter of this method is optional, as are all of its fields:

MessagingIndicator.showIndicator method

The showIndicator method is used to display a single indicator in the messaging menu. An indicator represents a persistent notification of a messaging event and provides means to follow up on this intent.

Arguments:

Throws:

Example code:

Unity.MessagingIndicator.showIndicator("Inbox", {count: 3});
Unity.MessagingIndicator.showIndicator("Message from Matt", {time: messageTimestamp, 
                                                             iconUrl: mattsAvatar});      
MessagingIndicator.clearIndicator method

The clearIndicator method is used to remove a previously displayed indicator by name, for example in response to the user following up on the associated message.

Arguments:

Throws:

Example code:

Unity.MessagingIndicator.clearIndicator("Message from Matt");
MessagingIndicator.clearIndicators method

The clearIndicators method removes all previous displayed indicators.

Example code:

Unity.MessagingIndicator.clearIndicators();
MessagingIndicator.addAction method

The addAction method of the MessagingIndicator interface is used to add an action shortcut to the applications' entry in the messaging menu. Note that unlike the Unity.addAction method, this interface does not deal with a hierarchy of actions.

Arguments:

Throws:

Example code:

Unity.MessagingIndicator.addAction("Compose New Message", onComposeActivated);      
MessagingIndicator.removeAction method

The MessagingIndicator.removeAction method is used to remove a previously added action by name.

Arguments:

Throws:

Example code:

Unity.MessagingIndicator.removeAction("Compose New Message"); 
MessagingIndicator.removeActions method

The MessagingIndicator.removeActions method is used to remove all previously added actions.

Example code:

Unity.MessagingIndicator.removeActions(); 
MessagingIndicator.presence attribute

The MessagingIndicator.presence attribute is a read-only string describing the users requested messaging presence. It may take one of four values:

If your application exposes some sort of presence, respecting the value selected by the user is a courtesy.

MessagingIndicator.onPresenceChanged method

The MessagingIndicator.presenceChanged method is used to receive notifications in response to the user presence status' changes.

Arguments:

Throws:

Example code:

function presenceChanged () {
   if (Unity.MessagingIndicator.presence == "offline") {
      signUserOut();
   }
}

Unity.MessagingIndicator.onPresenceChanged(presenceChanged);    
The Unity.Launcher interface

The Launcher interface can be used to display small amounts of information to the user through the Launcher icon. Also actions may be added to the Launcher Quicklist, enabling the user to quickly access key application functionality.

 interface UnityLauncherInterface {
   method setCount (Integer count);
   method clearCount ();
	
   method setProgress (Number progress);
   method clearProgress ();

   method setUrgent (Boolean urgnet);

   method addAction (String name, Callback onActionInvoked);
   method removeAction (String name);
   method removeActions ();
}     
Launcher.setCount method

The setCount method is used to display an integer count on the applications'Llauncher icon. This is appropriate, to indicate a number of unhandled items, like unread messages.

Arguments:

Throws:

Example code:

Unity.Launcher.setCount(numUnreadMessages);      
Launcher.clearCount method

The clearCount method clears a previously set count value in the Launcher icon, causing a return to the default state.

Example code:

Unity.Launcher.clearCount();
Launcher.setProgress method

The setProgress method is used to display a progress bar on the applications' Launcher icon. This is appropriate, for example, to display progress of a lengthy file transfer.

Arguments:

Throws:

Example code:

Unity.Launcher.setProgress(numUnreadMessages);      
Launcher.clearProgress method

The clearProgress method clears a previously set launcher progress value, causing the icon to return to its default state.

Example code:

Unity.Launcher.clearProgress();
Launcher.setUrgent method

The Launcher.setUrgent method sets the urgent state of the Launcher. This is used to communicate that the application is requesting the user's attention. The urgent state will automatically be cleared by Unity when the user reponds to the application, or after a timeout.

Arguments:

Throws:

Example Code:

Unity.Launcher.setUrgent(true); 
Launcher.addAction method

The Launcher.addAction method may be used to add Quicklist actions to the applications' Launcher icon. The interface and functionality are similar to the MessagingIndicator.addAction interface, but the Launcher is suitable for more general actions. Quicklist actions may for example be useful to quickly jump to specific categories of an applications views.

Arguments:

Throws:

Example code:

Unity.Launcher.addAction ("Science", onScienceAction);
Unity.Launcher.addAction ("Sports", onSportsAction);
Unity.Launcher.addAction ("Entertainment", onEntertainmentAction);
Launcher.removeAction method

The Launcher.removeAction method is used to remove a previously added Quicklist action by name.

Arguments:

Throws:

Example code:

Unity.Launcher.removeAction("Recent Document");
Launcher.removeActions method

The Launcher.removeActions method is used to remove all previously added quicklist actions.

Example code:

Unity.Launcher.removeActions();
The Unity.MediaPlayer interface

The Unity.MediaPlayer interface is suitable for applications which play back audio or video content. It is possible both to export metadata about the currently playing media (for quick viewing by the user), and hook into the Unity Media Controls: allowing your users to control the media with the same interface used for native applications.

enumeration UnityPlaybackState {
   Playing,
   Paused
}

dictionary UnityTrackMetadata {
   String title;

   optional String album;
   optional String artist;

   optional String artLocation;
}

interface UnityMediaPlayerInterface {
   method setTrack (UnityTrackMetadata trackMetadata);

   method onPrevious (Callback onPreviousCallback);
   method onNext (Callback onNextCallback);
   method onPlayPause (Callback onPlayPauseCallback);

   method onPrevious (Callback onPreviousCallback);
   method onNext (Callback onNextCallback);
   method onPlayPause (Callback onPlayPauseCallback);

   method getPlaybackstate (Callback response);
   method setPlaybackstate (UnityPlaybackState state);

   method setCanGoNext (boolean cangonext);
   method setCanGoPrev (boolean cangoprev);
   method setCanPlay (boolean canplay);
   method setCanPause (boolean canpause);
}	      
UnityPlaybackState enumeration

The UnityPlaybackState enumeration is used to indicate the current status of Media playback.

Values:

UnityTrackMetadata dictionary

The UnityTrackMetadata dictionary specifies the metadata of a single track, to be displayed in the Unity Sound Menu. The following property is mandatory:

There are three optional properties:

MediaPlayer.setTrack method

The setTrack method is used to expose metadata of the current media associated with your application. This will be displayed in the Unity Sound menu, allowing the user to view media information at a glance.

Arguments:

Throws:

Example code:

var trackInfo = {title: "Synchronous Grabs on my Heart",
                 album: "Love in the key of Compiz",
                 artist: "Sam Spilsbury"};

Unity.MediaPlayer.setTrack (trackInfo);
MediaPlayer.onNext method

The onNext method is used to register a callback, invoked when the user activates the "Next" action in the Unity Media Controls.

Arguments:

Throws:

Example code:

Unity.MediaPlayer.onNext (onNextTrack); 
MediaPlayer.onPrevious method

The onPrevious method is used to register a callback invoked when the user activates the "Previous" action in the Unity Media Controls.

Arguments:

Throws:

Example code:

Unity.MediaPlayer.onPrevious (onPreviousTrack);   
MediaPlayer.onPlayPause method

The onPlayPause method is used to register a callback invoked when the user activates the "PlayPause" action in the Unity Media Controls.

Arguments:

Throws:

Example code:

Unity.MediaPlayer.onPlayPause (onPlayPauseTrack);      
setCanGoNext method

The setCanGoNext method is used to enable or disable the "Next" action. For example, to disable it when playing the last track of a media collection.

Example code:

Unity.MediaPlayer.setCanGoNext(false);
      
setCanGoPrevious method

The setCanGoPrevious method is used to enable or disable the "Previous" action. For example to disable it when playing the first track of a media collection.

Example code:

Unity.MediaPlayer.setCanGoPrevious(false);
      
setCanPlay method

The setCanPlay method is used to enable or disable the "Play" action. For example, to disable it while media content is still buffering.

Example code:

Unity.MediaPlayer.setCanPlay(false);
      
setCanPause method

The setCanPause method is used to enable or disable the "Pause" action. For example, to disable it while an advertisement is being displayed.

Example code:

Unity.MediaPlayer.setCanPause(false);
      
Appendix A: URI Schemes

This appendix describes the particular format of URI parameters in the Unity Webapps API. Several URI schemes are supported: