Browser API

The HTML Browser API is an extension of the HTML <iframe> element that allows web apps to implement browsers or browser-like applications. It currently works in (privileged) chrome code on Firefox desktop (version 47 and above) and privileged and certified apps on B2G/Firefox OS.

Browser API concepts and usage

The Browser API consists of two major parts:

• Custom <iframe> attributes: By adding a mozbrowser attribute to the <iframe> element we can make it appear like a top-level browser window to the embedded content. This means that window.top, window.parent, window.frameElement, etc. should not reflect the frame hierarchy. We can also embed an open web app in the iframe if we include an additional mozapp attribute containing the path to the app's manifest.
• API extensions: The API includes several new methods and events to manipulate and listen for changes to the embedded content's state, interited by the HTMLIFrameElement interface.

Browser API interfaces

To support the requirement of a browser <iframe>, the HTMLIFrameElement DOM interface has been extended with new methods that give the <iframe> some super powers. For more information, see the HTMLIFrameElement's Browser API methods.

Events

In order to allow an application to manage the browser <iframe>, the application can listen for new events about what's happening within the browser <iframe>. The following new events can be listened for:

mozbrowseractivitydone

Sent when something inside the browser <iframe> triggers a web activity, and that web activity's message is consumed by the receiving app.

mozbrowserasyncscroll

Sent when the browser <iframe> content scrolls (the APCZ version.) See also mozbrowserscroll. Note that this is obsolete.

mozbrowseraudioplaybackchange

Sent when audio starts or stops playing within the browser <iframe> content.

mozbrowsercaretstatechanged

Sent when the text selected inside the browser <iframe> content changes.

mozbrowserclose

Sent when window.close() is called within a browser <iframe>.

mozbrowsercontextmenu

Sent when a browser <iframe> tries to open a context menu. This allows  handling of the <menuitem> element available within the browser <iframe>'s content.

mozbrowserdocumentfirstpaint

Sent when a new paint occurs on any document in the browser <iframe>.

mozbrowsererror

Sent when an error occurs while trying to load content within a browser <iframe>.

mozbrowserfindchange

Sent when a search operation is performed on the browser <iframe> content (see HTMLIFrameElement search methods.)

mozbrowserfirstpaint

Sent when the <iframe> paints content for the first time (this doesn't include the initial paint from about:blank.)

mozbrowsericonchange

Sent when a new icon (e.g. <link rel="icon"> or <link rel="apple-touch-icon">) is available in the browser <iframe>'s content.

mozbrowserloadend

Sent when the browser <iframe> has finished loading all its assets.

mozbrowserloadstart

Sent when the browser <iframe> starts to load a new page.

mozbrowserlocationchange

Sent when a browser <iframe>'s location changes.

mozbrowsermanifestchange

Sent when a the path to the app manifest changes, in the case of a browser <iframe> with an open web app embedded in it.

mozbrowsermetachange

Sent when a <meta> elelment is added to, removed from or changed in the browser <iframe>'s content.

mozbrowseropenwindow

Sent when window.open() is called within a browser <iframe>.

mozbrowseropentab

Sent when a new tab is opened within a browser <iframe> as a result of the user issuing a command to open a link target in a new tab (for example ctrl/cmd + click.)

mozbrowserresize

Sent when the browser <iframe>'s window size has changed.

mozbrowserscroll

Sent when the browser <iframe> content scrolls.

mozbrowserscrollareachanged

Sent when the available scrolling area in the browser <iframe> changes. This can occur on resize and when the page size changes (while loading for example.)

mozbrowserscrollviewchange

Sent when asynchronous scrolling (i.e. APCZ) starts or stops.

mozbrowsersecuritychange

Sent when the SSL state changes within a browser <iframe>.

mozbrowserselectionstatechanged

Sent when the text selected inside the browser <iframe> content changes. Note that this is obsolete, and newer implementations use mozbrowsercaretstatechanged instead.

mozbrowsershowmodalprompt

Sent when alert(), confirm(), or prompt() are called within a browser <iframe>.

mozbrowsertitlechange

Sent when the document title changes within a browser <iframe>.

mozbrowserusernameandpasswordrequired

Sent when an HTTP authentification is requested.

mozbrowseropensearch

Sent when a link to a search engine is found.

mozbrowservisibilitychange

Sent when the visibility state of the current browser iframe <iframe> changes, for example due to a call to setVisible().

Firefox OS permissions

Any Firefox OS app that wants to embed a browser frame must have the browser permission within its app manifest.

{
  "permissions": {
    "browser": {}
  }
}

Additionally, to embed another Firefox OS app, the app must have the embed-apps permission.

{
  "permissions": {
    "browser": {},
    "embed-apps": {}
  }
}

Specifications

This API isn't part of any official specification.

Browser Compatibility

[1] Supported in chrome code only.

See also

• Using the Browser API
• HTMLIFrameElement
• <iframe>