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.
Channel:
These events are persisted until the channel is active. A "Channel" event sent by a user will be sent to all the users in the channel including themselves. These are stored persistently on Channel attributes and can be accessed even after users leave the channel or the channel session ends. They will be cleared only if the channel remains empty (has no members) for a couple of minutes.
We can use "Channel" event to store information like the topic of the discussion, the current speaker, or the status of a poll, which should be visible and consistent to all participants.

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

send

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
);

on

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);

    }, []);

...

off

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.

off(eventName?: string , listener?: Function ) : void

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>
  );
}

Types

PersistanceLevel

enum PersistanceLevel {
  "None" = 1,
  "Sender",
  "Session",
  "Channel",
}

ReceiverUid

ReceiverUid: UidType | UidType[]

Unsubscribe

interface Unsubscribe {
  (): void;
}

EventCallback

interface EventCallbackPayload {
  payload: string;
  persistLevel: PersistanceLevel;
  sender: UidType;
  ts: number;
}

export type EventCallback = (args: EventCallbackPayload) => void;