Repository files navigation

sysend.js is a small library that allows to send messages between pages that are open in the samebrowser. It also supports Cross-Domain communication (Cross-Origin). The library doesn't have anydependencies and uses the HTML5 LocalStorage API or BroadcastChannel API. If your browser don'tsupport BroadcastChannel (seeCan I Use) then you cansend any object that can be serialized to JSON. With BroadcastChannel you can send any object (itwill not be serialized to string but the values are limited to the ones that can be copied by thestructured cloning algorithm).You can also send empty notifications.

Tested on:

GNU/Linux: in Chromium 34, Firefox 29, Opera 12.16 (64bit)
Windows 10 64bit: in IE11 and Edge 38, Chrome 56, Firefox 51
MacOS X El Captain: Safari 9, Chrome 56, Firefox 51

All cross-domain communication is disabled by default with Safari 7+. Because of a feature thatblocks 3rd party tracking for iframe, and any iframe used for cross-domain communication runs ina sandboxed environment. That's why this library like any other solution for cross-domaincommunication, don't work on Safari.

Since version 115 Google Chrome introduced Third-party storage partitioning. Because of this feature,Cross-domain communication only works on subdomains. There will probably be a way to share the contextusing some kind of permission API, that in the future may also land in Safari (hopefully). More informationabout this can be found in#54.Information about the API can also be found in Google Chrome documentation:Storage Partitioning

There is a new API: Storage Access API. It's available when youregister for theOrigin Trial.

You can register two and more domains, you will have a token that you need to add to the HTML files (in the head tag):

<metahttp-equiv="origin-trial"content="<TOKEN>"/>

You can also use the HTTP header:

Origin-Trial: <TOKEN>

Right now, the API only works with localStorage fallback (when inside iframes).

Includesysend.js file in your html, you can grab the file from npm:

npm install sysend

or bower

bower install sysend

you can also get it from unpkg.com CDN:

https://unpkg.com/sysend

or jsDelivr:

https://cdn.jsdelivr.net/npm/sysend

jsDelivr will minify the file. From my testing it's faster than unpkg.com.

window.onload=function(){sysend.on('foo',function(data){console.log(data.message);});varinput=document.getElementsByTagName('input')[0];document.getElementsByTagName('button')[0].onclick=function(){sysend.broadcast('foo',{message:input.value});};};

Tracking is high level API build on top ofon() andbroadcast(), that allows to manage windows/tabs. You can sent message directly to other windows/tabs:

sysend.track('message',({data, origin})=>{console.log(`${origin} send message "${data}"`);});sysend.post('<ID>','Hello other window/tab');

and listen to events like:

sysend.track('open',(data)=>{console.log(`${data.id} window/tab just opened`);});

Other tracking events includes: close/primary/secondary executed when window/tab is closed or become primary or secondary. Track method was added in version 1.6.0. Another required event isready (added in 1.10.0) that should be used when you want to get list of windows/tabs:

sysend.track('ready',()=>{sysend.list().then(tabs=>{console.log(tabs);});});

withlist() method andopen/close events you can implement dynamic list of windows/tab. That will change when new window/tab is open or close.

letlist=[];sysend.track('open',data=>{if(data.id!==sysend.id){list.push(data);populate_list(list);}});sysend.track('close',data=>{list=list.filter(tab=>data.id!==tab.id);populate_list(list);});sysend.track('ready',()=>{sysend.list().then(tabs=>{list=tabs;populate_list(list);});});functionpopulate_list(){select.innerHTML='';list.forEach(tab=>{constoption=document.createElement('option');option.value=tab.id;option.innerText=tab.id;select.appendChild(option);});}

In version 1.16.0 this code was abstracted into:

sysend.track('update',(list)=>{populate_list(list);});

This can be simplified with point free style:

sysend.track('update',populate_list);

In version 1.15.0 new API was added calledrpc() (build on top of tracking mechanism) that allow to use RPC (Remote Procedure Call) between open windows/tabs.

constrpc=sysend.rpc({get_message(){returndocument.querySelector('input').value;}});button.addEventListener('click',()=>{rpc.get_message('<ID>').then(message=>{console.log(`Message from other tab is "${message}"`);}).catch(e=>{console.log(`get_message (ERROR)${e.message}`);});});

If you want to add support for Cross-Domain communication, you need to call proxy method with url on target domainthat haveproxy.html file.

sysend.proxy('https://jcubic.pl');sysend.proxy('https://terminal.jcubic.pl');

on Firefox you need to addCORS for the proxy.html that will be loaded into iframe (seeCross-Domain LocalStorage).

if you want to send custom data you can use serializer (new in 1.4.0) this APIwas created for localStorage that needs serialization.

Example serializer can bejson-dry:

sysend.serializer(function(data){returnDry.stringify(data);},function(string){returnDry.parse(string);});

orJSON5:

sysend.serializer(function(data){returnJSON5.stringify(string);},function(string){returnJSON5.parse(string);});

Since version 1.10.0 as a security mesure Cross-Domain communication has been limited to only those domains that are allowed.To allow domain to listen to sysend communication you need to specify channel inside iframe. You need add your origins to thesysend.channel() function (origin is combination of protocol domain and optional port).

• Simple demo using iframes.
• All feature demo (this one require open in two tabs/windows, there is also link to other domain).
• ReactJS shopping cart synchronization.
• multiple window tracking demo. Open the link in multiple windows (not tabs). First window will track position and size for all windows.
• Multiple windows with interactive Canvas demo, this demo draws circle on the Canvas that follow the mouse. Open the page in multiple windows (not tabs). The best effect is when the circle is between two windows.

sysend object:

To see details of using the API, seedemo.html source code orTypeScript definition file.

The story of this library came from my question on StackOverflow from 2014:Sending notifications between instances of the page in the same browser, with hint from user calledNiet the Dark Absol, I was able to create a PoC of the solution using localStorage. I quickly created a library from my solution. I've also explained how to haveCross-Domain LocalStorage. The blog post have steady number of visitors (actually it's most viewed post on that blog).

And the name of the library is just random word "sy" and "send" suffix. But it can be an backronym forSynchronizing Send as in synchronizing application between browser tabs.

• CSRF Protection Problem and How to Fix it
• Synchronizacja stanu aplikacji www między zakładkami

The library was featured in:

• Web Tools Weekly
• JavaScript Weekly
• Impressive Webs
• Front-end Architecture
• Frontend Planet

Copyright (C) 2014Jakub T. Jankiewicz
Released under theMIT license

This is free software; you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.