@studio.sandbox/stdio-post-message

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
• StdioPostMessage
  • emitToChild
  • emitToParent
  • setMessageListener
  • destroyMessageListener
  • addAllowedOrigin
  • sendPerformanceObservations
• metricsCollected
• destroyPerformanceObserver

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, 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

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