Skip to content
This repository has been archived by the owner on Mar 15, 2018. It is now read-only.

iframe install messaging API

Jump to bottom
diox edited this page Nov 20, 2014 · 1 revision

Marketplace iframe-install messaging API

As the name implies, iframe-install.html is an iframe that handles app installs in Marketplace. But as it grew we added a bunch of features to it, which are documented below.

Why an iframe

We have to use a central origin for all app manipulation done by the Marketplace. That allows us to do navigator.mozApps.getInstalled() calls to fetch all apps we have installed.

Doing everything from https://marketplace.firefox.com origin instead of app://marketplace.firefox.com has several benefits:

  • Some people tweak allowed_from in their manifests. When they do, they usually whitelist our https:// origin and not our app:// origin.
  • It means we are not dependent on our Marketplace app. Everything can be done from Marketplace in your browser.
  • We can allow access to this proxy to other apps/websites by whitelisting their origin

Setup

Assuming your origin is whitelisted, it's easy:

// First, set up a handler for the messages the iframe is going to send:
window.onmessage = function(e) {
    console.log(e);
}

// Then, add the iframe...
var iframe = document.createElement('iframe');
iframe.src = 'https://marketplace.firefox.com/iframe-install.html';
document.body.appendChild(iframe);

// ... And start communicating with it!
iframe.contentWindow.postMessage({name: 'getInstalled'}, 'https://marketplace.firefox.com')

Message API

The communication is done by sending an object through postMessage(). The object sent needs to have a name property indicating the command you want to send, and in some cases additional properties for parameters.

When a response is returned, it will also be done through a postMessage() back to the caller. The message will be an object containing various properties depending on the command used. Multiple messages could be sent back, particularly in the case of errors. If an error occurs, an additional error property will be present, containing an object formed like this: {error: <ERROR_NAME>} where <ERROR_NAME> will be a string identifier.

Here are the available commands and their parameters:

getInstalled

Returns an array containing all the manifest URLs for the apps installed by the iframe origin. Uses navigator.mozApps.getInstalled() behind the scenes.

Example Usage

iframe.contentWindow.postMessage({name: 'getInstalled'}, ...)

Returned message

{name: 'getInstalled', result: <INSTALLED>}, where <INSTALLED> is an array containing all the manifest URLs for the apps installed by the iframe origin.

launch-app

Launches an app already installed.

Parameters

  • manifestURL: the manifest URL corresponding to the app we want to launch

Example Usage

iframe.contentWindow.postMessage({name: 'launch-app', manifestURL: 'https://example.com/manifest.webapp'}, ...)

install-package

Installs an app. Contrary to what the name implies, it supports both packaged and hosted apps, as long as the data.product.is_packaged parameter is passed correctly. Uses navigator.mozApps.installPackage() or navigator.mozApps.install() behind the scenes.

Parameters

  • data an object containing:
  • product: an object should contain the following properties: is_packaged, manifest_url, id and name.
  • opt: an optional object. If it has a data property, that will be passed directly to the underlying DOM method used.

Example Usage

iframe.contentWindow.postMessage({name: 'install-package', data: {product: {id: 42, name: 'Example App', is_packaged: true, manifest_url: 'https://example.com/manifest.webapp'}}}, ...)

Returned message

{appId: <PRODUCT>.id, product: <PRODUCT>, 'name': 'install-package'}.

check-for-update

Check if an update is available for a particular app. Uses <app>.checkForUpdate() behind the scenes.

Parameters

  • manifestURL: the manifest URL corresponding to the app we want to check updates for

Example Usage

iframe.contentWindow.postMessage({name: 'check-for-update', manifestURL: 'https://example.com/manifest.webapp'}, ...)

Returned message

{manifestURL: <MANIFEST_URL>, result: <UPDATE_AVAILABLE>, type: <TYPE>, name: 'check-for-update'}. <UPDATE_AVAILABLE> will contain the boolean indicating whether an app is available at this time. <TYPE> is mostly useful for debugging and contains the original event type that followed the underlying checkForUpdate() call. Those two properties will not be returned when an error occurs.

apply-update

Downloads an update for an app. Uses <app>.download() behind the scenes.

Parameters

  • manifestURL: the manifest URL corresponding to the app we want to update.

Example Usage

iframe.contentWindow.postMessage({name: 'apply-update', manifestURL: 'https://example.com/manifest.webapp'}, ...)

Returned message

{manifestURL: <MANIFEST_URL>, name: 'apply-update'}, when the download is finished sucessfully.

Clone this wiki locally