App State Library

Turnkey

Embed-SDK React

Embed-SDK Web

Provides accessors for various app states used in App Builder. Some accessors accept a selector method that allows for selective subscribing of data.

turnkey

You can access them under the customization-api module as a named export.

react-sdk

You can access them under the @appbuilder/react module as a named export.

web-sdk

You can access them under the @appbuilder/web module as a named export.

---

useRecording(selector?: Selector): RecordingContextInterface

The Recording app state governs the App Builder cloud recording functionality.

RecordingContextInterface

Key	Type	Description
isRecordingActive	boolean	Indicates if cloud recording is active in the application
startRecording	() => void	Starts cloud recording
stopRecording	() => void	Stops cloud recording

Usage example of the app state:

turnkey

import { useRecording } from "customization-api";

...

const { isRecordingActive, startRecording, stopRecording } = useRecording();

react-sdk

import { useRecording } from "@appbuilder/react";

...

const { isRecordingActive, startRecording, stopRecording } = useRecording();

web-sdk

import { useRecording } from "@appbuilder/web";

...

const { isRecordingActive, startRecording, stopRecording } = useRecording();

---

useSidePanel(selector?: Selector): SidePanelContextInterface

The SidePanel app state governs the sidePanel ui.

SidePanelContextInterface

Key	Type	Description
sidePanel	SidePanelType	Active sidepanel name
setSidePanel	( sidepanel: SidePanelType ) => void	Method to set active sidepanel name

SidePanelType

Name	Value
None	0
Participants	1
Chat	2
Settings	3

Usage example of the app state:

turnkey

import { useSidePanel, SidePanelType } from "customization-api";

...

const { sidePanel, setSidePanel } = useSidePanel();

react-sdk

import { useSidePanel, SidePanelType } from "@appbuilder/react";

...

const { sidePanel, setSidePanel } = useSidePanel();

web-sdk

import { useSidePanel, SidePanelType } from "@appbuilder/web";

...

const { sidePanel, setSidePanel } = useSidePanel();

---

useChatUIControl(selector?: Selector): ChatUIControlInterface

The ChatUIControl app state governs the chat ui.

ChatUIControlInterface

Key	Type	Description
groupActive	boolean	Determines if group tab is active in chat sidepanel
setGroupActive	(status: boolean) => void	Method to set group tab active status
privateActive	boolean	Determines if private tab is active in chat sidepanel
setPrivateActive	(status: boolean) => void	Method to set private tab active status
selectedChatUserId	uidtype	Uid of the user selected in private chat tab
setSelectedChatUserId	(uid: uidtype ) => void	Method to set selected user
message	string	Content of message to be sent
setMessage	(message: string) => void	Method to set content of message to be sent

Usage example of the app state:

turnkey

import { useRecording } from "customization-api";

...

const { isRecordingActive, startRecording, stopRecording } = useRecording();

react-sdk

import { useRecording } from "@appbuilder/react";

...

const { isRecordingActive, startRecording, stopRecording } = useRecording();

web-sdk

import { useRecording } from "@appbuilder/web";

...

const { isRecordingActive, startRecording, stopRecording } = useRecording();

---

useMessages(): MessageInterface

The Messages app state governs the chat messages.

MessageInterface

Key	Type	Description
groupMessages	MessageStoreInterface[]	Array of all the group messages
privateMessages	{ [key: string]: MessageStoreInterface[] }	Object containing all private messages
sendMessage	( msg: string, toUid?: number ) => void	Method to send a message. Sends group message if toUid is not passed
editMessage	( msgId: string, msg: string, toUid?: number ) => void	Method to edit a message
deleteMessage	( msgId: string, toUid?: number ) => void	Method to delete a message
groupUnreadCount	number	Number of unread group messages
setGroupUnreadCount	(count: number) => void	method to set number of unread group messages
individualUnreadCount	{ [key: string]: number }	object containing number of unread private messages corresponding to each uid
setIndividualUnreadCount	(count: { [key: string]: number } ) => void	method to set nubmer of unread private messages

MessageStoreInterface

key	type	description
createdTimestamp	number	message creation timestamp
updatedTimestamp?	number	last message update timestamp
msg	string	message content
msgId	string	message id
isDeleted	boolean	indicates if message is deleted
uid	UidType	uid of the message sender

usage example of the app state:

turnkey

import { useMessages } from "customization-api";

const {
  groupMessages,
  privateMessages,
  sendMessage,
  editMessage,
  deleteMessage,
  groupUnreadCount,
  setGroupUnreadCount,
  indIvidualUnreadCount,
  setIndividualUnreadCount,
} = useMessages();

react-sdk

import { useMessages } from "@appbuilder/react";

const {
  groupMessages,
  privateMessages,
  sendMessage,
  editMessage,
  deleteMessage,
  groupUnreadCount,
  setGroupUnreadCount,
  indIvidualUnreadCount,
  setIndividualUnreadCount,
} = useMessages();

web-sdk

import { useMessages } from "@appbuilder/web";

const {
  groupMessages,
  privateMessages,
  sendMessage,
  editMessage,
  deleteMessage,
  groupUnreadCount,
  setGroupUnreadCount,
  indIvidualUnreadCount,
  setIndividualUnreadCount,
} = useMessages();

---

useRender(selector?: Selector): RenderStateInterface

The Render app state governs the information necessary to render each user content view displayed in the videocall screen.

it is composed of:

RenderStateInterface

key	type	description
renderList	RenderObjects	Object containing information necessary to render the content view corresponding to each uid in the Render app state
activeUids	array<Uidtype>	Array of all uids in the Render app state

Each renderobject in the renderlist is passed as a prop to corresponding type of content component. All the resulting components are then passed to the layouts as an array to be rendered as desired.

For eg. The Render app state contains a renderobject of type:'rtc' for each user in the meeting by default stored in renderList. It is used to display user video feeds coming from AgoraRTC hence they contain all the necessary information like: uid to identify and subscribe to the video and audio, audio and video mute states to correctly display fallbacks and icons, etc. each Renderobject is passed as a prop to MaxVideoView unless overridden by CustomContent API. After which the resulting array of components is passed to layout to be rendered.

tip

You can add custom render objects to the render app state using the 'AddCustomContent' action in dispatch

Usage example of the app state:

turnkey

import { useRender } from "customization-api";

...

const { renderList, activeUids } = useRender();

react-sdk

import { useRender } from "@appbuilder/react";

...

const { renderList, activeUids } = useRender();

web-sdk

import { useRender } from "@appbuilder/web";

...

const { renderList, activeUids } = useRender();

---

useLocalUserInfo(): LocalUserInfo

The LocalUserInfo app state contains the local user information like uid, audio and video mute states etc.

Usage example of the app state:

turnkey

import { useLocalUserInfo } from "customization-api";

...

const {
  uid,
  audio,
  video,
  streamType,
  contentType,
  name,
  screenUid,
  offline,
} = useLocalUserInfo();

react-sdk

import { useLocalUserInfo } from "@appbuilder/react";

...

const {
  uid,
  audio,
  video,
  streamType,
  contentType,
  name,
  screenUid,
  offline,
} = useLocalUserInfo();

web-sdk

import { useLocalUserInfo } from "@appbuilder/web";

...

const {
  uid,
  audio,
  video,
  streamType,
  contentType,
  name,
  screenUid,
  offline,
} = useLocalUserInfo();

---

useLayout(selector?: Selector): LayoutContextInterface

The Layout app state governs the video call screen content display layout.

LayoutContextInterface

Key	Type	Description
currentLayout	string	Name of the current layout. Can be grid, pinned or any other key defined in the custom layout API
setLayout	( layoutName: string ) => void	Sets the current layout with given layout name

Usage example of the app state:

turnkey

import { useLayout } from "customization-api";

...

const { currentLayout, setLayout } = useLayout();

react-sdk

import { useLayout } from "@appbuilder/react";

...

const { currentLayout, setLayout } = useLayout();

web-sdk

import { useLayout } from "@appbuilder/web";

...

const { currentLayout, setLayout } = useLayout();

---

useMeetingInfo(selector?: Selector): MeetingInfoContextInterface

The MeetingInfo app state contains information about the active meeting.

MeetingInfoContextInterface

Key	Type	Description
isJoinDataFetched	boolean	Indicates meeting info has been fetched from the backend
data?	MeetingInfoData	Meeting info data

MeetingInfoData

Key	Type	Description
isHost	boolean	Indicates if the user joined using the Host URL or using the Attendee URL
meetingTitle	string	Meeting title
roomId	{  attendee: string,  host?: string, }	Host and attendee roomIds
pstn?	{  number: string,  pin: string }	PSTN info
isSeparateHostLink	boolean	Indicates if seperate host and attendee links generated
channel?	string	Channel name of current meeting
uid?	UidType	Uid of the local user
token?	string	RTC authentication token required to join the channel
rtmToken?	string	RTM authentication token required to join the channel
encryptionSecret?	string	Packet encryption secret
screenShareUid?	string	Uid of local user's screenshare
screenShareToken?	string	Authentication token for local user's screenshare

Usage example of the app state:

turnkey

import { useMeetingInfo } from "customization-api";

...

const { isJoinDataFetched, data } = useMeetingInfo();

react-sdk

import { useMeetingInfo } from "@appbuilder/react";

...

const { isJoinDataFetched, data } = useMeetingInfo();

web-sdk

import { useMeetingInfo } from "@appbuilder/web";

...

const { isJoinDataFetched, data } = useMeetingInfo();

---

useUserName(): [userName, setUserName]

The UserName app state governs the local user's display name.

Usage example of the app state:

turnkey

import { useUserName } from "customization-api";

...

const [userName, setUserName] = useUserName();

react-sdk

import { useUserName } from "@appbuilder/react";

...

const [userName, setUserName] = useUserName();

web-sdk

import { useUserName } from "@appbuilder/web";

...

const [userName, setUserName] = useUserName();

Returns:

userName: string

setUserName: (name: string) => void;

---

useRtc(selector?: Selector): RtcInterface

The RTC app state exposes the internal RtcEngine object as well as dispatch interface to perform various actions.

RtcInterface

Key	Type	Description
RtcEngine	RtcEngine	The RtcEngine object from the AgoraRTC SDK
dispatch	DispatchType	Method to perform various app builder actions. You can see list of available actions here.
setDualStreamMode	( mode: DualStreamMode ): void	Method to modify dual stream mode

danger

Avoid using RtcEngine directly to perform actions such as muting audio, joining a channel etc. Instead rely on Actions Library or Dispatch provided by the customization-api as they handle modifying the internal app states along with performing the required action.

Usage example of the app state:

turnkey

import { useRtc } from "customization-api";

...

const { RtcEngine, dispatch, setDualStreamMode } = useRtc();

react-sdk

import { useRtc } from "@appbuilder/react";

...

const { RtcEngine, dispatch, setDualStreamMode } = useRtc();

web-sdk

import { useRtc } from "@appbuilder/web";

...

const { RtcEngine, dispatch, setDualStreamMode } = useRtc();