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

---

---

useScreenshare(selector?: Selector): ScreenshareContextInterface

The Screenshare app state governs the App Builder Local User Screenshare functionality.

ScreenshareContextInterface

Key	Type	Description
isScreenshareActive	boolean	Indicates if screenshare is active for the local user
startScreenshare	() => void	Starts screenshare
stopScreenshare	() => void	Stops screenshare

Usage example of the app state:

turnkey

import { useScreenshare } from "customization-api";

...

const { isScreenshareActive, startScreenshare, stopScreenshare } = useScreenshare();

react-sdk

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

...

const { isScreenshareActive, startScreenshare, stopScreenshare } = useScreenshare();

web-sdk

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

...

const { isScreenshareActive, startScreenshare, stopScreenshare } = useScreenshare();

---

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
Transcript	4
VirtualBackground	5

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

---

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

---

useContent(selector?: Selector): ContentStateInterface

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

it is composed of:

ContentStateInterface

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

Each ContentObject in the defaultContent 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 Content app state contains a contentobject of type:'rtc' for each user in the room by default stored in defaultContent. 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 ContentObject is passed as a prop to MaxVideoView. After which the resulting array of components is passed to layout to be rendered.

tip

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

Usage example of the app state:

turnkey

import { useContent } from "customization-api";

...

const { defaultContent, activeUids } = useContent();

react-sdk

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

...

const { defaultContent, activeUids } = useContent();

web-sdk

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

...

const { defaultContent, activeUids } = useContent();

---

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,
  type,
  streamType
  name,
  screenUid,
  offline,
} = useLocalUserInfo();

react-sdk

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

...

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

web-sdk

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

...

const {
  uid,
  audio,
  video,
  type,
  streamType
  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();

---

useRoomInfo(selector?: Selector): RoomInfoContextInterface

The RoomInfo app state contains information about the active room.

RoomInfoContextInterface

Key	Type	Description
isJoinDataFetched	boolean	Indicates room info has been fetched from the backend
data?	RoomData	Room info data

RoomData

Key	Type	Description
isHost	boolean	Indicates if the user joined using the Host URL or using the Attendee URL
meetingTitle	string	Room title
roomId	{  attendee: string,  host?: string, }	Host and attendee roomIds
pstn?	{  number: string,  pin: string }	PSTN info
isSeparateHostLink	boolean	Indicates if separate host and attendee links generated
channel?	string	Channel name of current room
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 { useRoomInfo } from "customization-api";

...

const { isJoinDataFetched, data } = useRoomInfo();

react-sdk

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

...

const { isJoinDataFetched, data } = useRoomInfo();

web-sdk

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

...

const { isJoinDataFetched, data } = useRoomInfo();

---

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 RtcEngineUnsafe object.

RtcInterface

Key	Type	Description
RtcEngineUnsafe	RtcEngineUnsafe	The RtcEngineUnsafe object from the AgoraRTC SDK
setDualStreamMode	( mode: DualStreamMode ): void	Method to modify dual stream mode

danger

Avoid using RtcEngineUnsafe 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 { RtcEngineUnsafe, setDualStreamMode } = useRtc();

react-sdk

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

...

const { RtcEngineUnsafe, setDualStreamMode } = useRtc();

web-sdk

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

...

const { RtcEngineUnsafe, setDualStreamMode } = useRtc();