Ubuntu logo



Architecture essentials

In essence webapps are JavaScript code that is executed by a container, which generally is the web browser.

The JavaScript code can be installed locally or on the server itself. In terms of performance it does not make a noticeable difference, but the source for the scripts does have an impact on API compatibility. The recommendation is to provide the site-specific scripts on the server side, so that they are updated automatically if the website’s API changes.

On the client side, the other important layer is the integration with Ubuntu. This enables web sites to tap into the interfaces that the OS provides and use the standard Ubuntu user interactions. This effectively makes the user experience with the site as if it were just another native app.

For users this means starting and switching to their favorite sites comfortably as an app and getting notifications, voice control and any other supported integration features. For developers, this means increasing the visibility and user satisfaction with their websites.

Supercharge your sites with Ubuntu webapps

In order to use the Web API the first step is to identify as an application to Unity. Unity is the set of technologies that provide Ubuntu’s distinctive user experience. 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.

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

Ubuntu integration points


The notification interface is the simplest Unity API:

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

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.

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"}

This will allow the user to view metadata about your media through the Unity interface.

You can also hook your application into the Media Menu controls:



It is possible to export a hierarchy of actions from your application in to the Unity HUD (Heads-UP Display). 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");

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

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

Unity.MessagingIndicator.addAction("Compose New Message",

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

This API both allows you to add indications of activity, and messaging related actions.


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


// Later

You can also use the Launcher Quicklist functionality to expose important actions or bookmarks. This is especially 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);