IPostMessagePlugin

The plugin that is given the access to handle postMessage events from iframe components. The plugin listens for window.postMessage events from embedded iframes and triggers portal-side actions (such as showing toasts, modals, or updating items) by calling the postMessageCallback with an IPostMessageCallbackMessage.

The direction: the portal hands the callback to the plugin through setPostMessageCallback, and the plugin invokes it to ask the portal for something. Receiving the frame's messages is the plugin's own window.addEventListener("message", ...) — on window, not window.parent, since a module plugin runs in the portal's own window, and inside a component effect, where the cleanup runs. Check event.origin, and list the frame's origin in the manifest's cspDomains.

Examples

PostMessage handler with toast notification

class Plugin implements IPostMessagePlugin {
  postMessageCallback: (message: IPostMessageCallbackMessage) => void = () => {};

  setPostMessageCallback = (callback: (message: IPostMessageCallbackMessage) => void): void => {
    this.postMessageCallback = callback;
  };

  getPostMessageCallback = (): ((message: IPostMessageCallbackMessage) => void) => {
    return this.postMessageCallback;
  };
}

const plugin = new Plugin();

// In a real plugin this subscription belongs in a component effect.

window.addEventListener("message", (event) => {
  try {
    if (event.origin !== "https://frame.example.com") return;

    const data = typeof event.data === "string" ? JSON.parse(event.data) : event.data;
    if (data?.source !== "my-plugin") return;

    plugin.postMessageCallback({
      actions: [Actions.showToast],
      toastProps: [{
        type: ToastType.success,
        title: "Message Received",
      }],
    });
  } catch {
    // ignore non-JSON messages
  }
});

PostMessage handler with modal dialog

window.addEventListener("message", (event) => {
  try {
    if (event.origin !== "https://frame.example.com") return;

    const data = typeof event.data === "string" ? JSON.parse(event.data) : event.data;
    if (data?.source !== "my-plugin") return;

    plugin.postMessageCallback({
      actions: [Actions.showModal],
      modalDialogProps: {
        dialogHeader: "Frame Response",
        dialogBody: body,
        displayType: ModalDisplayType.modal,
      },
    });
  } catch {
    // ignore non-JSON messages
  }
});

Methods

setPostMessageCallback()

setPostMessageCallback(callback: (message: IPostMessageCallbackMessage) => void): void;

Sets the postMessage callback function. This method is called by the portal to register the callback that the plugin will use to communicate actions back to the portal.

Parameters

Parameter	Type	Description
callback	(message: IPostMessageCallbackMessage) => void	The callback function provided by the portal for the plugin to invoke

Returns

void

getPostMessageCallback()

getPostMessageCallback(): (message: IPostMessageCallbackMessage) => void;

Gets the current postMessage callback function.

Returns

The currently registered postMessage callback function

(message: IPostMessageCallbackMessage): void;

Parameters

Parameter	Type
message	IPostMessageCallbackMessage

Returns

void

Properties

Property	Type	Description
postMessageCallback	(message: IPostMessageCallbackMessage) => void	A callback function that is called by the plugin to trigger portal-side actions in response to postMessage events received from embedded iframes. The portal sets this callback via setPostMessageCallback. The plugin invokes it with an IPostMessageCallbackMessage containing the desired actions and their properties.