HelperApps.jsm

Add-ons using the techniques described in this document are considered a legacy technology in Firefox. Don't use these techniques to develop new add-ons. Use WebExtensions instead. If you maintain an add-on which uses the techniques described here, consider migrating it to use WebExtensions.

Starting from Firefox 53, no new legacy add-ons will be accepted on addons.mozilla.org (AMO) for desktop Firefox and Firefox for Android.

Starting from Firefox 57, WebExtensions will be the only supported extension type. Desktop Firefox and Firefox for Android will not load other extension types.

Even before Firefox 57, changes coming up in the Firefox platform will break many legacy extensions. These changes include multiprocess Firefox (e10s), sandboxing, and multiple content processes. Legacy extensions that are affected by these changes should migrate to WebExtensions if they can. See the "Compatibility Milestones" document for more information.

A wiki page containing resources, migration paths, office hours, and more, is available to help developers transition to the new technologies.

Mobile Only in Gecko 27.0
Available only in Firefox Mobile as of Gecko 27.0 (Firefox 27.0 / Thunderbird 27.0 / SeaMonkey 2.24)

Note: HelperApps.jsm is still under development. The API may change. Use with care!

The HelperApps.jsm JavaScript code module offers utility methods for finding and sending data to other apps installed on the device.

Components.utils.import("resource://gre/modules/HelperApps.jsm");

Basic usage

HelperApps.jsm exports two symbols:

  1. a HelperApps object and
  2. an App constructor into their scope

Example:

let apps = HelperApps.getAppsForUri(uri);
// Assuming apps.length > 0
HelperApps.prompt(apps, {
  title:"Launch!",
  buttons: ["OK", "Cancel"]
}, function(result) {
  var index = result.button == 0 ? result.icongrid0 : undefined;
  if (index != undefined) apps[index].launch();
});

Property overview

App

App.name
App.isDefault
App.packageName
App.iconUri

Method overview

App

App.launch(nsIURI uri);

HelperApps

HelperApps.showPicker(App[] apps, Object promptOptions, Function callback)
HelperApps.getAppsForProtocol(String scheme)
HelperApps.getAppsForUri(nsIURI uri, Object flags = { filterHttp: true })
HelperApps.launchUri(nsIURI uri)

Methods

App.launch()

Launches an app with an nsIURI. This attempts to use an Implicit Android intent, and will not show an intent chooser.

void launch(nsIURI uri);

Parameters

uri
The nsIURI to launch

Example

let uri = Services.io.newURI("http://www.mozilla.org", null, null);
let apps = HelperApps.getAppsForUri(uri);
apps[0].launch(uri);

HelperApps.showPicker()

Uses Prompt.jsm to show a prompt asking users which app they want to launch

void showPicker(apps, options, callback)

Parameters

apps
A list of App objects that should be shown in the prompt
options

An object describing the dialog to be shown, commonly used to add a title/buttons. The same type of object that can be passed to a Prompt.jsm constructor.

Parameter Description
window The window that is opening this prompt. Optional
title The title to show on the prompt. Optional
message A message to show on the prompt. Optional
buttons An array of Strings to show as buttons on the prompt. Prompts on Android support a maximum of three buttons. Any more will be ignored. Optional
callback
A function to be called when the prompt returns. Similar to the callback called from Prompt.show().

Example

let apps = HelperApps.getAppsForUri(Services.io.newURI("http://www.mozilla.org", null, null)));
HelperApps.prompt(apps, {
  title: "Pick!",
  buttons: ["OK"]
}, function(result) {
  alert(apps[result.icongrid0].name);
});

HelperApps.getAppsForProtocol()

Get an array of App objects that can handle this protocol.

App[] getAppsForProtocol(protocol);

Parameters

Takes a string protocol

Return value

Returns an array of App objects. Array will be length zero if none are found.

Example

let httpHandlers = getAppsForProtocol("http");
alert("Http links can be opened with " + httpHandlers[0].name);

HelperApps.getAppsForUri()

Gets a list of App objects that are registered to open a particular uri

App[] getAppsForUri(uri, flags = { filterHttp: true })

Parameters

uri
The nsIUri of the page
flags
A set of flags to control the filter
Flag Description
filterHttp Should http handlers be filtered from the results. Defaults to true
filterBrowsers Should browsers be filtered from the results. Defaults to true
action The Android Intent action to use when filtering. Defaults to Intent.ACTION_VIEW
packageName The Android packageName to use when filtering. Use if you want to find a particular app.
mimeType The mimetype of the uri. If not provided, the implementation will try to guess a mimetype from the nsIURI. If this is overridden, you don't even have to provide a uri to search for, and can instead search for handlers of a particular mimetype.

Return value

Returns a list of App objects that are registered to open a particular uri

Example

let url = "http://www.foo.com/myfile.dat";
let apps = HelperApps.getAppsForUri(Services.io.newURI(url, null, null), { mimeType: "foo/bar" });
alert(url + " can be opened with " + httpHandlers[0].name);

HelperApps.launchUri()

Sends an nsIURI as an intent to the Android system. This may show an Android native Intent chooser if multiple apps are available (and none are marked as default).

void launchUri(nsIURI uri);

Parameters

Takes an nsIURI to launch.

Return value

None

Example

HelperApps.launchUri(Services.io.newURI("http://www.google.com", null, null));

Document Tags and Contributors

 Contributors to this page: rebloor, andrewtruongmoz, wbamberg, moneytoo, wesj, Murph
 Last updated by: rebloor,