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

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

method external.getUnityObject(String version);

The external.getUnityObject method returns the Unity API object.

Arguments:

• String version: Version of the API to request, currently this must be "1.0".

Returns:

• The Unity API object.

Throws:

• ArgumentException: Thrown if any input parameter is not compatible with the expected type for that parameter.
• VersionException: Thrown if an invalid version is specified.

Example code:

var Unity = external.getUnityObject("1.0");

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

• Unity.Notification interface
• Unity.MediaPlayer interface
• Unity.MessagingIndicator interface
• Unity.Launcher interface

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 is a specification of a dictionary containing Unity initialization data. Three parameters are required:

• name: The application name, this should be suitable for displaying to users.
• iconUrl: A URL to an icon which will be associated with the application. This should be at least 128x128 to appear in the Switcher without pixelation. See the appendix on URIs and Resources for details as to the format of this argument.
• onInit: A callback invoked when initialization is complete. This will not always be immediate. Therefore usage of the Unity API before onInit is invoked will produce no results. This is guaranteed by an implementation.

There are two optional parameters:

• homepage: A URI containing the homepage for your application, this will be used when users launch your application from the shell. If specified this parameter follows the same semantics as assignment to document.domain in Mozilla. See the Same origin policy for JavaScript on MDN for details. If not specified, this will be set to the value of document.location.
• domain: Specify a domain for your site. If omitted document.domain will be used. As applications are identified by the tuple (name,domain) this can be useful if you use multiple subdomains (foo.myapp.com and bar.myapp.com). This parameter follows the same semantics as assignment to document.domain in Mozilla. See the Same origin policy for JavaScript on MDN for details.

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:

• UnityInitParameters initializationParameters: a dictionary of initialization parameters (defined above).

Throws:

• ArgumentException: Thrown if any input parameter is not compatible with the expected type for that parameter.
• DomainException: Thrown if the homepage or domain parameter of UnityInitParameters is specified and fails to pass the same origin check.

Example code:

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

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

Arguments:

• name: A string describing the action name. This must always begin with '/' and contain a list of '/' separated alphanumeric (plus whitespace) action components.
• onActionInvoked:
A callback invoked when the action is externally triggered through the Unity interface.

Throws:

• ArgumentException: Thrown if any input parameter is not compatible with the expected type for that parameter.

Example code:

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

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

Arguments:

• name: The name of the action to remove. If no such action exists, this call has no effect.

Throws:

• ArgumentException: Thrown if any input parameter is not compatible with the expected type for that parameter.

Example code:

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

The Unity.removeActions method removes all previously added actions.

Example code:

Unity.removeActions();

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);
}      

The showNotification method presents a single notification to the user.

Arguments:

• summary: A string summarizing the content of the notification. This should be a few words at most.
• body: The body of the notification. Note that this interface is for transient notifications. It is unlikely more than 120 characters will be displayed.
• iconUrl: An optional parameter specifying the location of an icon to use with the notification. If this is omitted, the application icon as specified in the parameters to Unity.init will be used. See the appendix on URIs and resources for details, as to the format of this string.

Throws:

• ArgumentException: Thrown if any input parameter is not compatible with the expected type for that parameter.

Example code:

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

The Unity.MessagingIndicator interface has three main components:

• An interface for displaying persistent messaging indicators.
• An interface to provide some messaging related shortcuts.
• An interface to read the users' messaging presence.

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 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:

• count: An integer specifying a message count, to be displayed to the user.
• time: A JavaScript date object representing the time at which a messaging event occurred.
• iconUrl: A URL to use as a specialized icon for this indicator. This is usually not necessary. Avoid overuse of this parameter as it may create a cluttered result. See the Appendix on Resources and URIs for a full description of the format of this string.
• callback: A callback invoked when the indicator is activated by the user. Note, even if no callback has been supplied, activating an indicator will always cause the most recent instance of your application to be raised.

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:

• name: A name for the Indicator object. This will be displayed as the label for the indicator and should as such be a user-friendly string.
• indicatorProperties: An optional UnityIndicatorProperties dictionary describing the indicator to show. If this is omitted, a default object will be used (empty, except the field time: Date.now()). If an indicator with name already exists, it's properties will be updated and the users attention will be requested again.

Throws:

• ArgumentException: Thrown if any input parameter is not compatible with the expected type for that parameter.

Example code:

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

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:

• name: The name of the indicator to clear. If no such indicator exists, the interface will perform no action. In this case the implementation guarantees not to produce an error.

Throws:

• ArgumentException: Thrown if any input parameter is not compatible with the expected type for that parameter.

Example code:

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

The clearIndicators method removes all previous displayed indicators.

Example code:

Unity.MessagingIndicator.clearIndicators();

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:

• name: A name for the action. This will be used as the action label in the Messaging Menu and as such it should be a user-friendly string.
• onActionInvoked: A callback invoked when the action is activated by the user.

Throws:

• ArgumentException: Thrown if any input parameter is not compatible with the expected type for that parameter.

Example code:

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

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

Arguments:

• name: The name of the action to remove. If no such action exists, this call has no effect.

Throws:

• ArgumentException: Thrown if any input parameter is not compatible with the expected type for that parameter.

Example code:

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

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

Example code:

Unity.MessagingIndicator.removeActions(); 

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

• "available" - The user has indicated she is available to receive messages.
• "away" - The user is away from her device, but would like to remain visible.
• "busy" - The user would like to remain visible, and is present at her device, but does not wish to be disturbed.
• "offline" - The user has indicated that she would not like to remain visible.

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

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

Arguments:

• onPresenceChanged: A callback invoked when the user's requested presence has changed.

Throws:

• ArgumentException: Thrown if any input parameter is not compatible with the expected type for that parameter.

Example code:

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

Unity.MessagingIndicator.onPresenceChanged(presenceChanged);    

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 ();
}     

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:

• count - An integer value to display on the applications Launcher icon.

Throws:

• ArgumentException: Thrown if any input parameter is not compatible with the expected type for that parameter.

Example code:

Unity.Launcher.setCount(numUnreadMessages);      

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();

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:

• progress - A floating point value in the range of [0,1] to display as progress on the applications launcher icon.

Throws:

• ArgumentException: Thrown if any input parameter is not compatible with the expected type for that parameter.

Example code:

Unity.Launcher.setProgress(numUnreadMessages);      

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

Example code:

Unity.Launcher.clearProgress();

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:

• urgent: A boolean value, for the new urgent state to request.

Throws:

• ArgumentException: Thrown if any input parameter is not compatible with the expected type for that parameter.

Example Code:

Unity.Launcher.setUrgent(true); 

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:

• name: The action name. This will be used as a label in the application Quicklist, and so it should be a user-friendly string.
• onActionInvoked: A callback to invoke when the user activates the action.

Throws:

• ArgumentException: Thrown if any input parameter is not compatible with the expected type for that parameter.

Example code:

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

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

Arguments:

• name: The name of the action to remove. If no such action exists, this call has no effect.

Throws:

• ArgumentException: Thrown if any input parameter is not compatible with the expected type for that parameter.

Example code:

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

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

Example code:

Unity.Launcher.removeActions();

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);
}	      

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

Values:

• Playing: Media is currently playing, and the PlayPause button (if any) should display a pause icon.
• Paused: Media is currently paused (or not playing), and the PlayPause button (if any) should display a play icon.

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

• title: A track title. This will be displayed in the Sound Menu, and so this string should be suitable for user-friendly.

There are three optional properties:

• arist: A track artist, representing the performer or creator of the media (as appropriate). This will be displayed in the Sound Menu, and so this string should be suitable for user-friendly.
• album: A track album, representing a collection the media belongs to. In addition to Albums of music, it may be used to indicate a collection of videos.
• artLocation: An URI to an image file representing artwork or a preview assosciated with the track. See the appendix on URIs and resources for details on the formatting of this parameter.

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:

• trackMetadata: A object with UnityTrackMetadata properties containing information about the current media track.

Throws:

• ArgumentException: Thrown if any input parameter is not compatible with the expected type for that parameter.

Example code:

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

Unity.MediaPlayer.setTrack (trackInfo);

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

Arguments:

• onNextCallback: A callback invoked when the "Next" action is activated.

Throws:

• ArgumentException: Thrown if any input parameter is not compatible with the expected type for that parameter.

Example code:

Unity.MediaPlayer.onNext (onNextTrack); 

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

Arguments:

• onPreviousCallback: A callback invoked when the "Previous" action is activated.

Throws:

• ArgumentException: Thrown if any input parameter is not compatible with the expected type for that parameter.

Example code:

Unity.MediaPlayer.onPrevious (onPreviousTrack);   

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

Arguments:

• onPlayPauseCallback: A callback invoked when the "PlayPause" action is activated.

Throws:

• ArgumentException: Thrown if any input parameter is not compatible with the expected type for that parameter.

Example code:

Unity.MediaPlayer.onPlayPause (onPlayPauseTrack);      

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);
      

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);
      

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);
      

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);
      

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

• http and https: URIs of the form http(s)?://HOST(:PORT)?/PATH. See the appendix on resource handling for details on size limits and caching behavior.
• data: URIs of the form data:MIMETYPE;base64,BASE64DATA. This is compatible with the Data URI format from canvas elements and the primary use of this scheme.
• theme: URIs of the form theme://ICON-NAME. These URIs are used to refer to icons by name from the users' current icon theme. For details see the freedesktop.org icon naming specification, and the corresponding implementation in GTK+3.