The Unity Web API is a toolkit for web applications to integrate with the Ubuntu Desktop. This is a developers guide, information about Webapps in Unity for users can be found here. For a web developer, the Unity Web API provides a collection of ways to increase the presence of your application on the users Desktop, and streamline key user journeys. Points of integration include, a spot on the Unity Launcher, integration with the Messaging and Music menus, or even exposing actions to the new Unity HUD!

The Unity Web API is currently implemented as a technology preview in the form of a Firefox extension. For information about installing the Unity Webapps System visit the WebApps team on launchpad.

Continue reading, for a 10 minute Quickstart guide to integrating your Web App with Unity. If you have gotten of the ground, and are looking to do more: reference documentation for the API is available.

In order, to integrate your application with Unity, the first step is to identify yourself as a desktop application. This is done through the Unity.init method:

function unityReady() {
  // Integrate with Unity!
}

Unity.init({name: "Unity Web Tutorial",
            iconUrl: "http://www.ubuntu.com/tutorialIcon.png",
            onInit: unityReady});

On the first invocation for a particular Web Application, this will request to the user that you wish to integrate with the desktop, and call the onInit member of the initialization dictionary if the user accepts. On further calls, onInit will be immediately invoked. Using the Unity API before onInit has been invoked will produce no results. You can try executing this code now.

Already this gets you quite a lot! A space on the Unity launcher, and integration with application management features. Let's now start to look at some of the specific API.

See the reference documentation for a full listing of parameters to Unity.init

The notification interface is the simplest Unity API:

Unity.Notification.showNotification("Attention", "Lorem ipsum dolor sit amet");

Try executing this now.

The Notification interface is suitable for displaying transient information to the user. Information presented in notifications should not require a decision from the user (and in fact there is no way to ask for one). Furthermore, consider the notification a nicety for the user, rather than put information which it is critical for the user to see.

A full description of the Notification interface can be found in the reference documentation.

For an application which presents media to the user, such as sound or video, consider integrating with the Unity media controls.

var trackInfo = {title: "Synchronous Grabs on my Heart",
                 album: "Love in the Key of Compiz",
                 artist: "Sam Spilsbury",
                 artLocation: "http://www.ubuntu.com/exampleCoverArt.svg"}
Unity.MusicPlayer.setTrack(trackInfo);

This will allow the user to view metadata about your media through the Unity interface. Try executing this now and check in your Media menu!

You can also hook your application in to the Media Menu controls:

Unity.MusicPlayer.onNext(onNextTrackCallback);
Unity.MusicPlayer.onPrevious(onPreviousTrackCallback);
Unity.MusicPlayer.onPlaypause(onPlaypauseCallback);

For full documentation on the MusicPlayer interface, see the reference documentation.

It is possible to export a hierarchy of actions from your application in to the Unity HUD. This may be of particular benefit for applications which feature complex nested menus. The API is simple:

Unity.addAction("/File/Rename", function () {
                                   alert("Got callback");
                                });

Go ahead try executing this snippet now, and finding the Rename action in your Unity HUD.

Details of the Unity.addAction method are presented in the reference documentation.

For messaging centric applications, such as those featuring Chat or Mail, the Messaging Menu can allow you to provide the user with a quick way to view activity, and follow up for more detail.

Unity.MessagingIndicator.showIndicator("Inbox", {count: numberOfMessages, 
                                                 callback: viewInboxCallback});
Unity.MessagingIndicator.showIndicator("Check out the Unity Web API", {time: new Date(), 
                                                                       callback: viewMessage});

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

// Later
Unity.MessagingIndicator.clearIndicator("Check out the Unity Web API");

This API both allows you to add indications of activity, and static messaging related actions. Try executing this code now and checking your messaging menu to see the results.

The Reference Documentation contains a full list of indicator methods and propertie.

The launcher API both allows you to display simple information to the user through icon overlays.

Unity.Launcher.setCount(3);
Unity.Launcher.setProgress(0.4);
Unity.Launcher.setUrgent(true);

// Later
Unity.Launcher.clearCount();

Try executing this code now, and watching your Launcher (TODO: Currently icons are not automatically added to launcher so this is unclear, fixed before release obviously...).

You can also use the Launcher Quicklist functionality to expose a few important actions/bookmarks to your user. This is espescially appropriate if your apps views are easily divided in to a few categories.

Unity.Launcher.addAction("Science", scienceActionCallback);
Unity.Launcher.addAction("Sports", scienceActionCallback);
Unity.Launcher.addAction("Entertainment", scienceActionCallback);

Try executing this snippet now, and right clicking on the Unity Web Tutorial Launcher Icon (if you have forgotten which it is, try running the previous snippet again) in order to see the results.

The complete Unity.Launcher interface is described, of course, in the reference documentation.