Introduction

The Unity Web API is a toolkit for Web applications and pages to integrate with the Ubuntu Desktop. This is a Developer's guide, for user-oriented information about webapps check here. For developers, the Unity Web API provides a collection of ways to increase the presence of your application on the users' Desktop, and expose application interactions through Unity components. Points of integration include a spot on the Unity Launcher, integration with the Messaging and Music menus, and even exposing actions to the new Unity HUD!

The Unity Web API is currently available for Ubuntu 12.10 (Quantal Quetzal), in both Firefox and Chromium. For information about installing the Unity Webapps System visit the WebApps team on Launchpad.

Continue reading for a 10 minute quick-start guide to integrating your Web App with Unity. If you have already started and are looking to do more: reference documentation for the API is available.

Quickstart

In order to use the Unity Web API the first step is to identify as an application to Unity. This is done with the Unity.init method: 

function unityReady() {
  // Integrate with Unity!
}
var Unity = external.getUnityObject(1.0); 

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

If the user has not yet enabled integration for your application the browser will request that the application wishes to integrate with Ubuntu, and call the onInit member of the initialization dictionary if the user accepts. On further calls, onInit will be immediately executed. Using the Unity API before onInit has been invoked will produce no results. You can try executing this code now.

Simple, but this already this gets you quite a lot! A space on the Unity launcher and integration with application management features.

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

Notifications

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 in an overlay window. Information presented in notifications should not require a users' input. Furthermore consider the notification as a nicety for the user, it is not recommended for displaying critical information.

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

Media Menu

Integration with the Unity media controls is available for applications which present media to the user, such as sound or video. 

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.MediaPlayer.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 into the Media Menu controls: 

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

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

Unity HUD

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. Execute this snippet now, and find the Rename action in your Unity HUD.

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

Messaging Menu

For messaging centric applications, such as those featuring Chat or Mail, the Messaging Menu allows the user a quick way to view recent 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 messaging related actions. Execute this code now and check your messaging menu to see the results.

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

Launcher

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

Execute this code now, and watch the launcher icon added when integrating the quick-start guide.

You can also use the Launcher Quicklist functionality to expose important actions or bookmarks. This is espescially appropriate if your site or application is easily divided in sections. 

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

Execute this snippet now. Right click on the Unity Web Tutorial Launcher Icon in order to see the results.

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