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