Use frame-to-frame messaging

This page describes how to send messages on the client side from an add-on running in the side-panel iframe to an add-on running in the main stage iframe. Frame-to-frame messaging only occurs on the client side, so message delivery is near instantaneous.

To send a message:

• From the side panel to the main stage, use the notifyMainStage() method.

    await sidePanelClient.notifyMainStage("YOUR_MESSAGE");

• From the main stage to the side panel, use the notifySidePanel() method.

    await mainStageClient.notifySidePanel("YOUR_MESSAGE");

The payload length must conform to its specified size limit.

To receive the message, the add-on must subscribe to the frameToFrameMessage callback. The following code sample shows how to subscribe to a frameToFrameMessage callback:

sidePanelClient.on('frameToFrameMessage', (arg: FrameToFrameMessage) => {
    // YOUR_CODE
});

The "Animation" sample add-on on GitHub includes a full example of frame-to-frame messaging. After the activity starts, the side panel notifies the main stage whenever the user changes an input. The main stage also subscribes to the frameToFrameMessage callback to receive updated state.

Notes

• Frame-to-frame messages sent by a given participant are only visible by that same participant. To send messages or state to other participants, learn how to share add-on state.

• Message delivery is only attempted once. To receive messages, the receiving panel must be open and the app must subscribe to the callback before the message is sent.

Related topics

• Implement the Co-Doing API