@studio.sandbox/stdio-post-message v1.2.2
StdioPostMessage
Caution: 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.
Features
✓ 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
Requirements
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).
Example
Please check the /examples
folder to view the most basic implementation.
Installing & Setup
$ npm install @studio.sandbox/stdio-post-message --save
import StdioPostMessage from 'stdio-post-message'
const pm = new StdioPostMessage()
App ready event
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.
API
Table of Contents
pmUtility
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.
StdioPostMessage
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, defaultDEFAULT_METHODS
)config.debug
Boolean logs information into the console (optional, defaultDEFAULT_DEBUG
)config.allowedOrigins
Array<String> origin urls which are allowed to be communicated with (optional, defaultDEFAULT_ALLOWED_ORIGINS
)config.maxEventPerMinute
Number rate limit of events one can receive per minute (optional, defaultMAX_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, defaulttrue
)data.retries
Number amount of retries (if "guaranteedDelivery" is set to "true") (optional, default1
)data.messageTimeout
Number amount of miliseconds after which you expect an acknowledgement (optional, defaultMESSAGE_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, defaulttrue
)data.retries
Number amount of retries (if "guaranteedDelivery" is set to "true") (optional, default1
)data.messageTimeout
Number amount of miliseconds after which you expect an acknowledgement (optional, defaultMESSAGE_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, defaultfalse
)
sendPerformanceObservations
Send an event to parent along with the recorded performanceMetrics
Parameters
payload
object the observed result by PerformanceObserver
metricsCollected
Initializing performanceObserver Metrics to observe: 'navigation', 'paint' Send back the result to parent using emitToParent function
destroyPerformanceObserver
Disconnect the performance observer to not have any further performance impact