Custom events

The Whiteboard SDK provides custom event methods for sending and receiving custom messages in real time in a room. You can use these methods to implement features such as message broadcasting, live chatting, giving likes, and sending gifts. This feature is for Web only.

This page describes how to send, receive, and stop receiving custom events.

Understand the tech

The Whiteboard SDK provides the following custom event methods:

• dispatchMagixEvent: Sends a custom event.
• addMagixEventListener: Adds a listener for a custom event.
• removeMagixEventListener: Removes a listener for a custom event.

To send and receive a custom event, follow these steps:

1. Define the name, payload, and callback function of the event.
2. Call addMagixEventListener to listen for the event.
3. Call dispatchMagixEvent to send the event. All users in the room listening for the event receive the event notification.
4. Call removeMagixEventListener to cancel listening for the event, if you want to stop receiving the event notification.

Prerequisites

To follow the procedure on this page, ensure that you have integrated the Whiteboard SDK into your project and implemented joining a room. For details, see Join the Whiteboard Room.

Implementation

The following section extends the Join the Whiteboard Room sample code to show the implementation of sending and receiving simple text messages by using the custom event methods.

Listen for and send a custom event

Add the following lines to the joinWhiteboard.js file:

var whiteWebSdk = new WhiteWebSdk({
    appIdentifier: "RMxxxAQ",
});

var joinRoomParams = {
    uuid: "a7xxx69",
    roomToken: "NETLESSROOM_YWxxxjk",
};

// Define the name and payload of the event.
var eventObject = {
    event: "Greetings",
    payload: "",
};

// Define the callback function of the event.
function onReceiveGreetings(eventObject) {
    // Output the event payload when receiving the Greetings event.
    console.log(eventObject.payload);
}

whiteWebSdk.joinRoom(joinRoomParams).then(function(room) {

    room.bindHtmlElement(document.getElementById("whiteboard"));

    // Add a listener for the Greetings event.
    room.addMagixEventListener("Greetings", onReceiveGreetings);

    // Send the Greetings event.
    room.dispatchMagixEvent("Greetings", "Hello, how do you do");

}).catch(function(err) {

    console.error(err);
});

Save the changes, refresh the index.html page, and open the console of your browser. You can see the following information on the console:

Hello, how do you do

Stop listening for a custom event

If you want to stop receiving the callback notification of a custom event, call removeMagixEventListener to remove the listener for the event.

For example, to stop listening for the Greetings event, add the following lines to the joinWhiteboard.js file:

whiteWebSdk.joinRoom(joinRoomParams).then(function(room) {

    room.bindHtmlElement(document.getElementById("whiteboard"));

    // Remove the listener for the Greetings event.
    room.removeMagixEventListener("Greetings", onReceiveGreetings);

}).catch(function(err) {

    console.error(err);
});

See also

Considerations

Note the following when implementing custom events:

• To ensure the stability of the dispatchMagixEvent method, Agora recommends that the payload of a custom event should not exceed 1 KB; otherwise, delay or freezes may occur in the whiteboard room.
• You cannot receive the notification of an event that is sent before you call addMagixEventListener.

API reference

• dispatchMagixEvent
• addMagixEventListener
• removeMagixEventListener