Custom Events Library
- Turnkey
- Embed-SDK React
- Embed-SDK Web
Custom Events
Provides methods to send and listen to custom events. These events can be sent to a specific user(s) in the channel or to all the user(s) in the channel.
- turnkey
- react-sdk
- web-sdk
You can access them under the customization-api
module as a named export.
You can access them under the @appbuilder/react
module as a named export.
You can access them under the @appbuilder/web
module as a named export.
These events can be sent to
- A specific user in the channel.
- A set of users in the channel.
- All the users in the channel.
These events can be sent with different levels of persistance.
None:
These events are short-lived. A "None" event sent by a user will only be available to other users in the room at that time. These events won't be available to users who join the room after the event has been sent.
Sender:
These events are persisted until the sender leaves the channel. A "Sender" event sent by a user will be available to other users in the room regardless of when they join as long as the sender is present in the room. These events won't be available to users who join the room after the sender has left the room.
Session:
These events are persisted until the session ends. A "Session" event sent by a user will be available to other users if there is at least one user present in the room. When the last user leaves a room, the session ends. All events are cleared when a session ends.
Import
customEvents object handles customization api events and provides methods for sending, subscribing and unsubscribing to events.
- turnkey
- react-sdk
- web-sdk
import { customEvents } from "customization-api";
import { customEvents } from "@appbuilder/react";
import { customEvents } from "@appbuilder/web";
Methods
Sends the event with the provided details.
send : ( eventName: string , payload: string , persistLevel: PersistanceLevel , receiver? : ReceiverUid ) : void
Prop | Type | Description |
---|---|---|
eventName | string | Name of the event to be sent |
payload | string | Payload to be sent along with the event |
persistLevel | PersistanceLevel | Sets the persistence of the event |
receiver? | ReceiverUid | Uid(s) to send the message to. Leave emtpy to send as a channel message to all users |
- turnkey
- react-sdk
- web-sdk
import { customEvents } from "customization-api";
...
// 1. Sending to specific user 0001 in the channel
customEvents.send(
"event-specific-single",
"Payload is Hello!!",
PersistanceLevel.None,
001
);
// 2. Sending to user(s) 001 002, 003in the channel
customEvents.send(
"event-specific-multiple",
"Payload is Hello!!",
PersistanceLevel.None,
[001, 002, 003]
);
// 3. Sending in the channel
customEvents.send(
"event-channel",
"Payload is Hello!!",
PersistanceLevel.None
);
import { customEvents } from "@appbuilder/react";
...
// 1. Sending to specific user 0001 in the channel
customEvents.send(
"event-specific-single",
"Payload is Hello!!",
PersistanceLevel.None,
001
);
// 2. Sending to user(s) 001 002, 003in the channel
customEvents.send(
"event-specific-multiple",
"Payload is Hello!!",
PersistanceLevel.None,
[001, 002, 003]
);
// 3. Sending in the channel
customEvents.send(
"event-channel",
"Payload is Hello!!",
PersistanceLevel.None
);
import { customEvents } from "@appbuilder/web";
...
// 1. Sending to specific user 0001 in the channel
customEvents.send(
"event-specific-single",
"Payload is Hello!!",
PersistanceLevel.None,
001
);
// 2. Sending to user(s) 001 002, 003in the channel
customEvents.send(
"event-specific-multiple",
"Payload is Hello!!",
PersistanceLevel.None,
[001, 002, 003]
);
// 3. Sending in the channel
customEvents.send(
"event-channel",
"Payload is Hello!!",
PersistanceLevel.None
);
Subscribes to the event. Use on method to add listener for specific event.
on( eventName: string , listener: EventCallback ) : Unsubscribe
Prop | Type | Description |
---|---|---|
eventName | string | Name of the event to be subscribed |
listener | Function | Callback method for the event to be called when event is received |
- turnkey
- react-sdk
- web-sdk
import react from "React";
import { customEvents } from "customization-api";
...
React.useEffect(() => {
const funcOne = (data) => {};
const funcTwo = (data) => {};
const funcThree = (data) => {};
// 1. Adding single anonymous listener
customEvents.on("event-one", (data)=> {console.log(data)});
// 2. Adding single named listener
customEvents.on("event-two", funcOne);
// 3. Adding multiple listener(s) to same event. Kindly note function name should be different when using multiple listeners
customEvents.on("event-three", funcTwo);
customEvents.on("event-three", funcThree);
}, []);
...
import React from "React";
import { customEvents } from "@appbuilder/react";
...
React.useEffect(() => {
const funcOne = (data) => {};
const funcTwo = (data) => {};
const funcThree = (data) => {};
// 1. Adding single anonymous listener
customEvents.on("event-one", (data)=> {console.log(data)});
// 2. Adding single named listener
customEvents.on("event-two", funcOne);
// 3. Adding multiple listener(s) to same event. Kindly note function name should be different when using multiple listeners
customEvents.on("event-three", funcTwo);
customEvents.on("event-three", funcThree);
}, []);
...
import { customEvents, React } from "@appbuilder/web";
...
React.useEffect(() => {
const funcOne = (data) => {};
const funcTwo = (data) => {};
const funcThree = (data) => {};
// 1. Adding single anonymous listener
customEvents.on("event-one", (data)=> {console.log(data)});
// 2. Adding single named listener
customEvents.on("event-two", funcOne);
// 3. Adding multiple listener(s) to same event. Kindly note function name should be different when using multiple listeners
customEvents.on("event-three", funcTwo);
customEvents.on("event-three", funcThree);
}, []);
...
Use off method to remove listener for specific event. If no listener is provided, all listeners added on eventName will be removed. If both eventName and listener are not provided, all events will be removed;
Additionally, method on
returns unbind
function. Call it and this listener
will be removed from event.
Prop | Type | Description |
---|---|---|
eventName? | string | Name of the event to be unsubscribed. If no event name provided all subscribed events will be unsubscribed |
listener? | Function | Method to unsubscribe. If no listener is provided, all listeners added on the eventName will be unsubscribed |
- Removing listener using calling unsubscribe method
- turnkey
- react-sdk
- web-sdk
import React from "React";
import { customEvents } from "customization-api";
...
React.useEffect(() => {
const funcListener = (data) => {};
const unbind = customEvents.on("event-zero", funcListener);
return () => {
// Remove specific single listener.
unbind();
}
}, []);
...
import React from "React";
import { customEvents } from "@appbuilder/react";
...
React.useEffect(() => {
const funcListener = (data) => {};
const unbind = customEvents.on("event-zero", funcListener);
return () => {
// Remove specific single listener.
unbind();
}
}, []);
...
import { customEvents, React } from "@appbuilder/web";
...
React.useEffect(() => {
const funcListener = (data) => {};
const unbind = customEvents.on("event-zero", funcListener);
return () => {
// Remove specific single listener.
unbind();
}
}, []);
...
- Removing a single listener by passing pass eventname and function.
- turnkey
- react-sdk
- web-sdk
import React from "React";
import { customEvents } from "customization-api";
...
React.useEffect(() => {
const funcOne = (data) => {};
// 1. Adding single named listener
customEvents.on("event-one", funcOne);
return () => {
// Remove single named listener
customEvents.off("event-one", funcOne);
}
}, []);
...
import React from "React";
import { customEvents } from "@appbuilder/react";
...
React.useEffect(() => {
const funcOne = (data) => {};
// 1. Adding single named listener
customEvents.on("event-one", funcOne);
return () => {
// Remove single named listener
customEvents.off("event-one", funcOne);
}
}, []);
...
import { customEvents, React } from "@appbuilder/web";
...
React.useEffect(() => {
const funcOne = (data) => {};
// 1. Adding single named listener
customEvents.on("event-one", funcOne);
return () => {
// Remove single named listener
customEvents.off("event-one", funcOne);
}
}, []);
...
- Removing a multiple listener by passing pass eventname and function.
- turnkey
- react-sdk
- web-sdk
import React from "React";
import { customEvents } from "customization-api";
...
React.useEffect(() => {
const funcOneFirst = (data) => {};
const funcOneSecond = (data) => {};
// 2. Adding multiple listener(s) to same event. Kindly note function name should be different when using multiple listeners
customEvents.on("event-one", funcOneFirst);
customEvents.on("event-one", funcOneSecond);
return () => {
// 1. Remove specific single listener.
customEvents.off("event-one", funcOneFirst);
// 2. Remove all listeners for a given specific event
// Here both funcOneFirst and funcOneSecond will be removed
customEvents.off("event-one")
}
}, []);
...
import React from "React";
import { customEvents } from "@appbuilder/react";
...
React.useEffect(() => {
const funcOneFirst = (data) => {};
const funcOneSecond = (data) => {};
// 2. Adding multiple listener(s) to same event. Kindly note function name should be different when using multiple listeners
customEvents.on("event-one", funcOneFirst);
customEvents.on("event-one", funcOneSecond);
return () => {
// 1. Remove specific single listener.
customEvents.off("event-one", funcOneFirst);
// 2. Remove all listeners for a given specific event
// Here both funcOneFirst and funcOneSecond will be removed
customEvents.off("event-one")
}
}, []);
...
import { customEvents, React } from "@appbuilder/web";
...
React.useEffect(() => {
const funcOneFirst = (data) => {};
const funcOneSecond = (data) => {};
// 2. Adding multiple listener(s) to same event. Kindly note function name should be different when using multiple listeners
customEvents.on("event-one", funcOneFirst);
customEvents.on("event-one", funcOneSecond);
return () => {
// 1. Remove specific single listener.
customEvents.off("event-one", funcOneFirst);
// 2. Remove all listeners for a given specific event
// Here both funcOneFirst and funcOneSecond will be removed
customEvents.off("event-one")
}
}, []);
...
- Removing all listeners
- turnkey
- react-sdk
- web-sdk
import React from "React";
import { customEvents } from "customization-api";
...
React.useEffect(() => {
const funcOne = (data) => {};
const funcTwo = (data) => {};
const funcThree = (data) => {};
customEvents.on("event-one", funcOne);
customEvents.on("event-two", funcTwo);
customEvents.on("event-three", funcThree);
return () => {
// Remove all events and their listener(s)
customEvents.off();
}
}, []);
...
import React from "React";
import { customEvents } from "@appbuilder/react";
...
React.useEffect(() => {
const funcOne = (data) => {};
const funcTwo = (data) => {};
const funcThree = (data) => {};
customEvents.on("event-one", funcOne);
customEvents.on("event-two", funcTwo);
customEvents.on("event-three", funcThree);
return () => {
// Remove all events and their listener(s)
customEvents.off();
}
}, []);
...
import { customEvents, React } from "@appbuilder/web";
...
React.useEffect(() => {
const funcOne = (data) => {};
const funcTwo = (data) => {};
const funcThree = (data) => {};
customEvents.on("event-one", funcOne);
customEvents.on("event-two", funcTwo);
customEvents.on("event-three", funcThree);
return () => {
// Remove all events and their listener(s)
customEvents.off();
}
}, []);
...
Example
- turnkey
- react-sdk
- web-sdk
import React from "React";
import { customEvents, PersistanceLevel } from "customization-api";
React.useEffect(() => {
// Adding Listener
const unbind = customEvents.on("hello-event", (data: EventCallback) => {
console.log(
`I have received payload ${data.payload} from user ${data.sender} at time ${data.timestamp} with persistance of ${data.persistLevel}`,
);
});
return () => {
// Removing listener
unbind();
};
}, []);
function App() {
// Sending event
const sendEvent = () =>
customEvents.send("hello-event", "Hello!!", PersistanceLevel.None);
return (
<div>
<button onClick={sendEvent}>Send event!</button>
</div>
);
}
import React from "React";
import { customEvents, PersistanceLevel } from "@appbuilder/react";
React.useEffect(() => {
// Adding Listener
const unbind = customEvents.on("hello-event", (data: EventCallback) => {
console.log(
`I have received payload ${data.payload} from user ${data.sender} at time ${data.timestamp} with persistance of ${data.persistLevel}`,
);
});
return () => {
// Removing listener
unbind();
};
}, []);
function App() {
// Sending event
const sendEvent = () =>
customEvents.send("hello-event", "Hello!!", PersistanceLevel.None);
return (
<div>
<button onClick={sendEvent}>Send event!</button>
</div>
);
}
import { customEvents, PersistanceLevel, React } from "@appbuilder/web";
React.useEffect(() => {
// Adding Listener
const unbind = customEvents.on("hello-event", (data: EventCallback) => {
console.log(
`I have received payload ${data.payload} from user ${data.sender} at time ${data.timestamp} with persistance of ${data.persistLevel}`,
);
});
return () => {
// Removing listener
unbind();
};
}, []);
function App() {
// Sending event
const sendEvent = () =>
customEvents.send("hello-event", "Hello!!", PersistanceLevel.None);
return (
<div>
<button onClick={sendEvent}>Send event!</button>
</div>
);
}