@meso-network/post-message-bus
v0.0.71
Published
Pass strongly typed messages across frames.
Downloads
5
Readme
@meso-network/post-message-bus
post-message-bus
is a Meso-specific library for sending strongly typed
messages across frames (iframes and parent windows) using
postMessage.
It is currently unavailable for standalone use.
View the CHANGELOG or read the
meso-js
docs.
Usage
From a parent frame (window)
import { createPostMessageBus } from "@meso-network/post-message-bus";
// Initialize the bus by providing an origin of the iframe to communicate with.
const bus = createPostMessageBus("https://iframe.origin");
// Listen for events
bus.on("CLOSE", () => {
console.log("close event called");
});
From inside an iframe
import { createPostMessageBus } from "@meso-network/post-message-bus";
// Initialize the bus by providing an origin of the parent frame to communicate with.
const bus = createPostMessageBus(window.location.ancestorOrigins[0]);
// Listen for events
bus.on("RETURN_SIGNED_MESSAGE_RESULT", (message) => {
console.log(message); // { payload: { signedMessage: "some-string" }}
});
// Emit events
bus.emit("REQUEST_SIGNED_MESSAGE", {
payload: {
messageToSign: "a message to be signed",
},
});
Reference
You can view the full type definitions here.
createPostMessageBus
The createPostMessageBus
function accepts target
origin to establish
postMessage
communication.
The origin must be valid (<protocol>://<domain>
) and cannot be *
.
The function returns either postMessageBus
object or an initialization error.
PostMessageBus
type PostMessageBus = {
/**
* Subscribe to an event using the message kind (name).
*
* The attached handler will be invoked each time this event is seen until the event handler is detached.
*/
on: (eventKind: MessageKind, handler: PostMessageHandlerFn) => PostMessageBus;
/**
* Send a message to a specific [origin](https://developer.mozilla.org/en-US/docs/Web/API/Location/origin). If the `targetOrigin` is omitted, the message will be broadcast to all origins (`*`).
*/
emit: (message: Message, targetOrigin?: string) => PostMessageBus;
/**
* Detach event handlers and end post message communications.
*/
destroy: () => void;
};
PostMessageBusInitializationError
type PostMessageBusInitializationError = {
/**
* A _developer_ friendly message containing details of the error.
*/
message: string;
};
Subscribe to events
You can subscribe to message events by using the .on
method from the returned
instance.
The method takes two arguments:
eventKind: MessageKind
– which message you'd like to subscribe toREQUEST_SIGNED_MESSAGE
: Request from Meso experience to parent window to initiate signing.RETURN_SIGNED_MESSAGE_RESULT
: Dispatch the result of a signature request from the parent window to the Meso experience.CLOSE
: Dispatch a message from the Meso experience to the parent window to close the experience.TRANSFER_UPDATE
: Dispatch a message from the Meso experience to the Partner Window when the transfer has been updated.ERROR
: Dispatch an error message from the Meso experience to the parent window.
handler: PostMessageHandlerFn
– a callback that accepts two arguments:
Emit events
You can emit message events by using the .emit
method from the returned
instance.
The method takes two arguments:
message: Message
– a strongly typed message (see types)targetOrigin?: string
– an optional, valid origin to send the postMessage to.