Netscape DevEdge

Skip to: [content] [navigation]

XPInstall Guidelines for Plugin Installations

XPInstall is a JavaScript-based installer technology that works across all the platforms that Mozilla and Netscape browsers based on Mozilla (such as Netscape 7) are deployed. It can be a way to ensure a smooth user-experience when obtaining plugins, without obliging the user to exit the browsing environment to launch a binary installer (the classic setup.exe experience on Windows) or obliging the user to restart their browser. For plugin vendors who have already written a native code (e.g. EXE) installer, XPInstall can wrap this native installer and run it so that the user never has to leave the browsing environment and click on the EXE to run it. This article presents a guideline for improving the plugin installation experience for Netscape Gecko browsers using XPInstall.

A Definition of Terms

XPInstall is an installer technology, and the name itself stands for "Cross Platform Install" (hence "XP" -- an abbreviation for "Cross Platform"). An XPInstall package is usually called an XPI package for short (and often pronounced "zippy"). This article is about how you can use XPInstall to install plugins to the browsers that support XPInstall.

An XPI Package is in fact a ZIP file with the XPI file extension (e.g. myPluginInstaller.xpi), and can be created on Windows by utilities such as WinZip. XPI Packages, like ZIP files, "contain" other files, typically:

You can create an XPInstall file by first zipping all the items you want installed with WinZip (create a ZIP archive) and then renaming it with the XPI file extension instead of the ZIP file extension.

Unlike native code installers (for example, files called setup.exe), the programming language for install operations in XPI is JavaScript. Since the file format that contains the software and the install.js JavaScript file is a cross-platform file (Zip) and since JavaScript is understood by Mozilla browsers on all platforms, often one single XPI package can be deployed on all platforms. This is, in fact, how skins and themes are installed to Mozilla browsers, changing their look and feel. This article focuses on how to install plugins.

Which Browsers Support XPInstall?

Currently, all Mozilla browsers released by support XPInstall, and a family of browsers based on Mozilla code support XPInstall. In particular, this includes:


What Does a Plugin Consist Of?

Plugins can consist of the following types of files, all of which can be installed via an XPI Package:

XPInstall can be used to install any combination of these files on an end-user's machine. For those familiar with Netscape Communicator 4.x's SmartUpdate technology, this will be a familiar idea.

A Brief History of Netscape Installer Technologies

This section is relevant if you are familiar with Netscape Communicator 4.x's SmartUpdate installer technology.
The use of JavaScript as the install logic is not unprecedented in Netscape browsers. Netscape Communicator 4.x uses the notion of SmartUpdate to install software, particularly plugins and Java applets to be run locally. SmartUpdate is not supported by Mozilla browsers (and Netscape/AOL browsers based on Mozilla such as Netscape 7), but because of the similarity between the two installer technologies, it is easy to convert your SmartUpdate files to XPInstall files. SmartUpdate involves a digitally signed JAR file which contained the software components to be installed as well as a JavaScript install.js file (called the install script) as the installer logic. Downloads and installs would be initiated with a security dialog box naming the certificate authority and the signer. Often, the SmartUpdate download was triggered via the pluginurl attribute of the embed tag:

<embed type="application/x-randomtype" src="myfile.typ" width="50" height="50"

In the example above, the pluginurl attribute points to the signed JAR file, which Netscape Communicator 4.x would then download (subject to the security dialog boxes) if the plugin was not located on the user's machine.
SmartUpdate differs from XPInstall in that: XPInstall for Mozilla-based browsers is analogous to SmartUpdate in Netscape Communicator 4.x browsers. Porting SmartUpdate deployments to XPInstall is trivial after gaining some familiarity with the new XPInstall API.

XPInstall provides a cohesive API to accomplish rapid installation and setup of plugin software for end-users. The benefit of using XPInstall is to provide a streamlined installation mechanism. This section discusses what an ideal XPInstall Package will do, as well as points out some of the JavaScript API calls that you will make to accomplish these install tasks. An ideal XPI Package will:

  1. Install to the current browser that is initiating the XPInstall installation via HTML or triggering an XPInstall installation via a Trigger Script. We will use the term current browser to refer to the browser that initiates the XPInstall download by visiting a site which requires a plugin that the current browser can not find locally. This step will involve the use of the initInstall API call to start everything off, and also the getFolder API call, which helps to locate the current browser's plugin directory.
  2. Install the plugin software to another location on the user's hard disk, so that other Mozilla-based browsers that the user may install later can find the plugin (the browser specific components) and pick it up. The goal is to ensure that future Netscape Gecko browsers that the user may install later can benefit from the installation that the user initiated with the current browser. An example might be that the current browser is Netscape 7, but later, the user downloads a beta of the AOL software using Netscape Gecko. Rather than re-initiate the download of the plugin with the yet another browser, the second Netscape Gecko browser can detect that an installation has already occurred. This discovery mechanism hinges on making the secondary install location available from looking at a common repository of metadata. On Windows, this is the Windows System Registry. Once again, this step involves calls to getFolder to locate a "well known" directory in which to install to as a secondary install location.
  3. On Windows: write Windows Registry keys that Netscape Gecko browsers (that get installed after the current browser) can parse to discover where the plugin is installed on the machine. In particular, the Windows Registry keys should point to the secondary install location so that future Netscape Gecko browsers can find and add to their list of available plugin locations. The exact format of these registry keys and how they should be written is covered in the section on the first install problem. To actually create and write keys to the Windows System Registry, you'll use the functions of the WinReg object.
  4. Ensure that the plugin that has just been installed is refreshed by correctly invoking the refreshPlugins API. By refreshing your plugin, you're ensuring that the plugin is available for use immediately, without obliging the user to restart their browser. This is one of the chief advantages of a smooth XPInstall experience.

The First Install Problem

The First Install Problem refers to the conditions arising when a plugin arrives on a user's machine before a browser arrives. The recommended install process addresses this issue, which is to install to a secondary location after installing to the current browser. In a nutshell, the first install problem can be summed up by the question: how can a browser which is installed on a user's machine after a given plugin has already been installed by the user benefit from the existing installation rather than download the same plugin again? In order to address this issue, plugin vendors are encouraged to:

A Breakdown of the APIs Used

The recommended plugin installation process makes use of the XPInstall APIs to install to the current browser's Plugins directory, install to a secondary location, and to write to the Windows System Registry to disclose this secondary location. This section traces some of the XPInstall APIs that can do this. A complete template of an XPI Package is also presented in this section. Not all the work needs to be done in JavaScript -- if you have a native installer (EXE) that recognizes Netscape Gecko browsers, and you merely wish to wrap the EXE installer in an XPI Package for a streamlined delivery to the client, you can easily do so. This section refers extensively to the XPInstall API Documentation.

Initializing Installation with Plugin Identifier

All XPInstall installations are initiated with the initInstall method of the Install Object. Since the Install Object is available to the install script, it need not be mentioned in the install script (e.g. there is no need to invoke Install.initInstall; simply invoking initInstall will suffice). The initInstall method is polymorphic, but here is a recommended invocation mechanism:

initInstall("My Plugin Software", ",version=2.5", "");
In the code snippet above, the initInstall method is invoked with three parameters:

Caveat: Certain versions of Mozilla-based browsers (such as Netscape 6.x) treat the use of the equals character ("=") as an illegal token and thus do not allow invocation of initInstall with strings containing "=". A workaround to this would be to detect if initInstall has failed, and then invoke it again without the "=" string. Here is an example:

var PLID = "MyPlugin.plug/version=6.5";
err = initInstall(SOFTWARE_NAME, PLID, VERSION);

if (err != 0)
	// install may have failed because of N6 and =
	// replace PLID with a simple string
	err = initInstall(SOFTWARE_NAME, "MyPluginString", VERSION);
	if (err != 0)

Note that above, the PLID contains an "=" and in case the XPI package is running on browsers that treat "=" as an illegal token, the workaround is to handle the error and invoke initInstall again.

Using XPInstall to Run an EXE (Native Code) Installer

If you wish to run a native installer (EXE) to install plugin software, but wish to make the delivery of this native installer streamlined and within the browser's process, then you ought to consider wrapping it in an XPI Package. From JavaScript, you can call XPInstall's execute method of the Install Object to execute the binary. You can also call the execute method of the File object if you wish to actually install the file you are executing, rather than have it deleted. You can pass command line parameters to the executable. An example of calling the execute method from the Install Object on an executable that has a temporary life span (and is not needed after one execution) is:

// Initialize the installation ....

// initInstall(..... ) has already been called

// Using the Install Object's execute method to block on a native installer

execute("setup.exe", "-s", true);	

// In the above sample, assume that running "setup -s" from the 
// Command Prompt runs the setup executable, and that  "-s" is some
// invocation parameter defined by the setup.exe file, perhaps to force
// the installer to run silently.  We are passing "-s" to the setup file.
// By passing 'true' we are telling the Install Script to block
// on the execution of the installable, and do it synchronously

// Must call performInstall to make it all happen...

err = getLastError();
if (!err)

Installing Plugin Files To the Current Browser

Installing to the current browser is the task that is the most important for the XPI Package to succeed in. Here is a code snippet that accomplishes this:

// Name of the files to be installed
var PLUGIN_FILE    = "NPMyPlugin.dll";
var COMPONENT_FILE = "NPMyPluginScriptablePeer.xpt";

// invoke initInstall to start the installation


var pluginFolder = getFolder("Plugins");

// verify disk space is appropriate


err = addFile(",version=", "", PLUGIN_FILE, pluginsFolder, null);
	if (err != 0)
		//alert("Installation of MyPlugin plug-in failed. Error code "+err);
		logComment("adding file "+PLUGIN_FILE+" failed. Errror conde: " + err);

		return err;

err = addFile(null, CULT_VERSION, COMPONENT_FILE, componentsFolder, null);
	if (err != 0)
		alert("Installation of MyPlugin component failed. Error code "+err);
		logComment("adding file "+COMPONENT_FILE+" failed. Error conde: " + err);

		return err;

Installing to a Secondary Location

For the purposes of solving the First Install Problem, it is necessary to install to a secondary location to ensure discoverability of the plugin by other Netscape Gecko browser in addition to the current browser. A good choice for this secondary location might be the Windows directory on Windows machines. Caveat: Because of possible administrator issues, handle errors carefully!

// Get the Windows System directory e.g. C:\WINNT\system32\ directory

var winDirectory = getFolder("Win System");

// Create the Folder C:\WINNT\system32\MyPlugin

var dllWin32Folder = getFolder("file:///", winDirectory+"\\MyPlugin\\");
//Install DLL to C:\Windows Folder
	copyErr = addFile("", VERSION, PLUGIN_FILE, dllWin32Folder, null);	
    if (copyErr != 0)
    	logComment("First Install:"+copyErr);
    	return copyErr;

// Install the XPT file to C:\WINNT\system32\MyPlugin folder

var xptWin32Folder = getFolder("file:///", winDirectory+"\\MyPlugin\\");
	copyErr = addFile("", VERSION, COMPONENT_FILE, xptWin32Folder, null);		
    if (copyErr != 0)
    	logComment("First Install:"+copyErr);
    	return copyErr;

Once the secondary installation has taken place, the Win32 Registry keys have to be updated to indicate information about where the secondary install location is, so that browsers can discover it. This is accomplished with the WinReg object that is exposed to XPInstall. The pieces all come together in the template below.

An XPInstall Template

We have provided you with a template for an install script which you might want to open in another tab or window. This install script does all of the following:

Certainly, this script is Windows-centric, but it is easy to port it to any other platform. Easier, perhaps, since the lengthy Win32 Registry manipulation need not occur on Linux or Mac OSX. The getFolder API provides you with enough "syntactic sugar" to determine other locations on the user's computer on different platforms and OS's. A single install.js is often capable of running on many different platforms.

Some Installation Concerns

This section gathers together some of the chief concerns about deploying XPI packages, notably: how ought a plugin download via XPI be initiated? And what about uninstalling plugins?

Triggering an XPInstall Download with a TriggerScript

A Trigger Script is web-page delivered piece of JavaScript that can automatically initiate an XPInstall download. This can be done conditionally, since Trigger Scripts can also detect what software has already been installed to the user's machine via XPInstall. This feature is useful for Web sites because:

Trigger Scripts are a recommended way of initiating an XPInstall download.

Triggering an XPInstall Download from HTML

In a manner analogous to how SmartUpdate downloads were initiated by the pluginurl attribute of the embed tag, XPInstall downloads can also be initiated by HTML tags invoking plugins, notably via the codebase attribute of the object tag. This is analogous to how Internet Explorer downloads CAB files pointed to by the codebase attribute of the object tag. Here's an example of a hypothetical object tag used to invoke MyPlugin (an imaginary application):

	<object id="thePlugin" type="application/x-myplugin" width="100" 
	height="100" codebase="http://location/XPI/myplugin.xpi">
<param .... >
In the above case, the codebase attribute points directly to the XPI Package, and if the browser can not identify any plugin to handle the (imaginary) application/x-myplugin MIME type, it will download the XPI Package.

Note: XPI Packages (files with the xpi extension) use the application/x-xpinstall MIME type. When serving XPI Packages from servers to clients, make sure that XPI Packages are served with this MIME type in the HTTP headers. Associate the application/x-xpinstall MIME type with XPI Packages.

The Uninstall Problem

In its current iteration, XPInstall does not have an affiliated uninstall technology. It can therefore only be used to install files or deliver native code installers to the client, and if uninstall is a legitimate concern, it might be wise to write a native code (EXE) uninstaller to remove the software. XPInstall can therefore be the "agent of delivery" to streamline the download of the EXE software, but ultimately, the logic of installation and uninstallation will be handled by EXE, which can then create files and registry entries and also clean up after itself upon removal.