Unity Web API Documentation

Unity Web API
Reference Documentation - v1.0
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:

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

The Unity API Object

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` dictionary

`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.

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

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

`Unity.addAction` method

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

`Unity.removeAction` method

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

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

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

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

- `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.

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

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

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

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

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

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

`MessagingIndicator.removeAction` method

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

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

- "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.
`MessagingIndicator.onPresenceChanged` method

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

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

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

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

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

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

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

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

`Launcher.removeAction` method

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

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

- `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.

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

- `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.

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

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

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

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

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

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

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

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

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

- `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.