Browser API
Non-standard
This feature is non-standard and is not on a standards track. Do not use it on production sites facing the Web: it will not work for every user. There may also be large incompatibilities between implementations and the behavior may change in the future.
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 amozbrowser
attribute to the<iframe>
element we can make it appear like a top-level browser window to the embedded content. This means thatwindow.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 additionalmozapp
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 alsomozbrowserscroll
. 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 usemozbrowsercaretstatechanged
instead. mozbrowsershowmodalprompt
- Sent when
alert()
,confirm()
, orprompt()
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 tosetVisible()
.
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": {} } }
Note: You can also include the browser:embedded-system-app
permission in your manifest if you want to enables an app opened in a browser <iframe>
to call methods of the API on — and listen and respond to related events fired by — itself (usually the parent window of the iframe
calls the Browser API.) This is available to internal (certified) apps only.
Specifications
This API isn't part of any official specification.
Browser Compatibility
Feature | Chrome | Firefox (Gecko) | Internet Explorer | Opera | Safari (WebKit) |
---|---|---|---|---|---|
Basic support | No support | 47 (47)[1] | No support | No support | No support |
Feature | Android | Android Webview | Firefox Mobile (Gecko) | Firefox OS | IE Mobile | Opera Mobile | Safari Mobile | Chrome for Android |
---|---|---|---|---|---|---|---|---|
Basic support | No support | No support | No support | 1.0.1 | No support | No support | No support | No support |
[1] Supported in chrome code only.
See also
License
© 2016 Mozilla Contributors
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-us/docs/web/api/browser_api