A small API built on top of `postMessage` to allow secure bi-directional communication between multiple children (iframes) and their parent.
npm install @studio.sandbox/stdio-post-messageCaution: This library is in early development and not finished or officially published yet! - internal preview build
> _StdioPostMessage_ is a small API built on top of postMessage to allow secure bi-directional communication between multiple children (iframes) and their parent.
✓ Communicate with children (iframes) or your parent window using postMessage
✓ Uses promises to enable message acknowledgement
✓ Has a rate-limit such that your website cannot be spammed with events
✓ No dependencies
✓ Works with multiple iframe tags
✓ Up to 10 message retries
This library uses ES2015+ features (e.x.: Array.prototype.includes, Promises, Spread-Operator) which you might need to polyfill depending on the targeted browser versions for your application when using bundlers. The umd dist file is compatible with IE11 and all other more modern browsers by default (polyfills included).
Please check the /examples folder to view the most basic implementation.
``bash`
$ npm install @studio.sandbox/stdio-post-message --save
`javascript`
import StdioPostMessage from 'stdio-post-message'
const pm = new StdioPostMessage()
An event sent from the app, to let know the studio client that an app is completely loaded, meaning it has load
all it's ajax request, DOM is loaded, and it's ready to be used.
In order to emit this event, use the emitToParent event and set APP_READY as the event name.
There is no need to send anything in the payload, since the studio client will be tracking the timestamp itself.
#### Table of Contents
- pmUtility
- StdioPostMessage
- emitToChild
- emitToParent
- setMessageListener
- destroyMessageListener
- addAllowedOrigin
- sendPerformanceObservations
- metricsCollected
- destroyPerformanceObserver
Copyright 2018 trivago N.V.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS-IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
Note: This is an unfinished lib still wip.
A helper to allow iframe communication using postMessage
Parameters
- config Object the complete configuration object (optional, default {})config.methods
- Object contains functions which are allowed to be called by others (optional, default DEFAULT_METHODS)config.debug
- Boolean logs information into the console (optional, default DEFAULT_DEBUG)config.allowedOrigins
- Array<String> origin urls which are allowed to be communicated with (optional, default DEFAULT_ALLOWED_ORIGINS)config.maxEventPerMinute
- Number rate limit of events one can receive per minute (optional, default MAX_EVENTS_PER_MINUTE)
#### emitToChild
Emit an event to a child (through an iframe)
Parameters
- data Object the complete data object being handed over (optional, default {})data.payload
- Object the data being handed over (optional, default {})data.event
- String the event name (optional, default '')data.selector
- (String \| Object) the css selector or element object of the iframe (optional, default '')data.guaranteedDelivery
- Boolean require a message acknowledgement (optional, default true)data.retries
- Number amount of retries (if "guaranteedDelivery" is set to "true") (optional, default 1)data.messageTimeout
- Number amount of miliseconds after which you expect an acknowledgement (optional, default MESSAGE_TIMEOUT)
Returns Promise
#### emitToParent
Emit an event to the parent (if you are within an iframe)
Parameters
- data Object the complete data object being handed over (optional, default {})data.payload
- Object the data being handed over (optional, default {})data.event
- String the event name (optional, default '')data.url
- String the url of the parent you want to send the event to (optional, default '')data.guaranteedDelivery
- Boolean require a message acknowledgement (optional, default true)data.retries
- Number amount of retries (if "guaranteedDelivery" is set to "true") (optional, default 1)data.messageTimeout
- Number amount of miliseconds after which you expect an acknowledgement (optional, default MESSAGE_TIMEOUT)
Returns Promise
#### setMessageListener
Set global 'message' event listener
#### destroyMessageListener
Destroy global 'message' event listener
#### addAllowedOrigin
Add a new url to the allowed origins
Parameters
- url String a complete url (optional, default false)
#### sendPerformanceObservations
Send an event to parent along with the recorded performanceMetrics
Parameters
- payload` object the observed result by PerformanceObserver
Initializing performanceObserver
Metrics to observe: 'navigation', 'paint'
Send back the result to parent using emitToParent function
Disconnect the performance observer to not have any further performance impact