Namespace crossOrigin

bus

• bus(options?: CrossOriginEventBusOptions): CrossOriginEventBus

• Creates an EventBus to enable cross-origin communication.

  import { crossOrigin } from '@paychex/platform-browser';
  
  const bus = crossOrigin.bus({ url: 'http://some.other-domain.com' });
  
  // listen for messages from some.other-domain.com
  bus.on('some-message', async function handle(arg1, arg2) { ... });
  
  // send messages to some.other-domain.com and process return values
  await bus.fire('some-event', 'abc', 123)
    .then((results) => { ... });
  

  IMPORTANT! Message arguments must be serializable as JSON. If not, the fire method will return a rejected Promise. For example:

  await bus.fire('message', undefined); // throws error
  await bus.fire('message', null); // okay
  await bus.fire('message', { key: undefined }); // okay
  

  example

  // parent (hosting) page
  // http://my.domain.com
  
  const bus = crossOrigin.bus({ url: 'http://some.other-domain.com' });
  
  // listen for messages from other domain
  bus.on('response', async function handler(arg1, arg2) {
    console.log(`received response: ${arg1}, ${arg2}`);
  });
  
  // send messages to the other domain
  await bus.fire('message', 'abc', 123).then(
    (results) => console.log(results),
    (error) => console.error(error),
  );
  
  // destroy the connection at any time
  bus.dispose();
  

  example

  // child (hosted) page
  // http://some.other-domain.com
  
  const store = stores.localStore();
  const bus = crossOrigin.bus({ origins: ['http://*.domain.com'] });
  
  // listen for messages from parent parge
  bus.on('message', async function handler(key, param) {
    const arg1 = await store.get(key);
    const arg2 = await someAsyncOperation(arg1, param);
    await bus.fire('response', arg1, arg2);
  });
  

  Parameters

  • options: CrossOriginEventBusOptions = {}

    Values used to customize the EventBus's behavior.

  Returns CrossOriginEventBus

  An EventBus that can be used to send messages between the two origins. The bus will have a new method, dispose, that can be used to tear down the connection.