The Agora Interactive 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 page describes how to send, receive, and stop receiving custom events.
The Agora Interactive 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:
addMagixEventListener
to listen for the event.dispatchMagixEvent
to send the event. All users in the room listening for the event receive the event notification.removeMagixEventListener
to cancel listening for the event, if you want to stop receiving the event notification.To follow the procedure on this page, ensure that you have integrated the Agora Interactive Whiteboard SDK into your project and implemented joining a room. For details, see Join a Whiteboard Room.
The following section extends the Join a Whiteboard Room sample code to show the implementation of sending and receiving simple text messages by using the custom event methods.
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
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);
});
Note the following when implementing custom events:
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.addMagixEventListener
.