Please note, this is a STATIC archive of website developer.mozilla.org from 03 Nov 2016, cach3.com does not collect or store any user information, there is no "phishing" involved.

Broadcast Channel API

This is an experimental technology
Because this technology's specification has not stabilized, check the compatibility table for usage in various browsers. Also note that the syntax and behavior of an experimental technology is subject to change in future versions of browsers as the specification changes.

The Broadcast Channel API allows simple communication between browsing contexts (that is windows, tabs, frames, or iframes) with the same origin (usually pages from the same site).

Note: This feature is available in Web Workers.

Broadcast channels are named and bound to a specific origin.

By creating a BroadcastChannel object, which is listening to the underlying channel, you are able to receive any message that has been posted to it. An interesting point is that you no longer have to maintain a reference to iframes or workers that you with to communicate with. They can simply “subscribe” to particular channels by constructing a BroadcastChannel, and have full-duplex (bi-directional) communication between all of them.

The principle of the Broadcast Channel API

Broadcast Channel interface

Creating or joining a channel

The BroadcastChannel interface is very simple. A client joins a specific broadcast channel by creating a BroadcastChannel object. The constructor takes one single parameter, the name of the channel, used to identify it. If it is the first to connect to a broadcast channel, the underlying resource is created.

// Connection to a broadcast channel
var bc = new BroadcastChannel("test_channel");

Sending a message

Posting a message is now trivial, it is enough to call the postMessage() method on the BroadcastChannel object. This method takes any object as argument, a very simple one like a DOMString text message, for example:

// Example of sending of a very simple message
bc.postMessage("This is a test message.");

There is no need for the message to be just a DOMString, any kind of object can be send. As the API doesn't associated any semantic to the messages, it is up to the participant to the channel to know what kind of messages to expect and what to do with them.

Receiving a message

When a message is posted, a message event will be dispatched to each BroadcastChannel object connected to this channel. There is no action by default, but a new function can be implemented using the onmessage event handler.

// Exemple of a simple event handler that only
// logs the event to the console
bc.onmessage = function (ev) { console.log(ev); }

Disconnecting a channel

To leave a channel, it is required to call the close() method on the object. This disconnects the link between the object and the underlying channel and allows garbage collection to happen.

// Disconnect the channel
bc.close()

Conclusion

The Broadcast Channel API is a very simple API and the self-contained interface allows cross-context communication. It can be used to detect user actions in other tabs within a same site origin environment, like when the user logs into an account. The messaging protocol is not defined and the different documents in the different contexts need to implement it themselves: there is no negotiation, nor requirement from the specification.

Specifications

Specification Status Comment
WHATWG HTML Living Standard
The definition of 'The Broadcast Channel API' in that specification.
Living Standard Initial definition.

Browser compatibility

Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari
Basic support 54 38 (38) No support 41 No support
Available in workers 54 38 (38) No support 41 No support
Feature Android Chrome for Android Firefox Mobile (Gecko) IE Mobile Opera Mobile Safari Mobile
Basic support No support 54 38.0 (38) No support No support No support
Available in workers No support 54 38.0 (38) No support No support No support

See also

Document Tags and Contributors

 Contributors to this page: ebidel, teoli, chrisdavidmills, fscholz
 Last updated by: ebidel,