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
- 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.
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
- react-sdk
- web-sdk
import { useRecording } from "customization-api";
...
const { isRecordingActive, startRecording, stopRecording } = useRecording();
import { useRecording } from "@appbuilder/react";
...
const { isRecordingActive, startRecording, stopRecording } = useRecording();
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
- react-sdk
- web-sdk
import { useScreenshare } from "customization-api";
...
const { isScreenshareActive, startScreenshare, stopScreenshare } = useScreenshare();
import { useScreenshare } from "@appbuilder/react";
...
const { isScreenshareActive, startScreenshare, stopScreenshare } = useScreenshare();
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: string
Pre-defined values for system usage: 'None' | 'Participants' | 'Chat' | 'Settings' | 'Transcript' | 'VirtualBackground'
To hide any Side Panel then setSidePanel to 'None'
setSidePanel('None')
To activate/display any existing Side Panel then setSidePanel with pre-defined values
setSidePanel('Participants')
To activate/display any Custom Side Panel(user-defined using customization API) then setSidePanel with custom side panel name
'Side-Panel-One' is name attribute which you have passed in customSidePanel API
setSidePanel('Side-Panel-One')
Usage example of the app state:
- turnkey
- react-sdk
- web-sdk
import { useSidePanel, SidePanelType } from "customization-api";
...
const { sidePanel, setSidePanel } = useSidePanel();
import { useSidePanel, SidePanelType } from "@appbuilder/react";
...
const { sidePanel, setSidePanel } = useSidePanel();
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 |
inputHeight | number | Initial Height of TextInput, it will expand dynamically based upon no of lines of text input. |
setInputHeight | (height: number) => void | Method to update the height of TextInput |
showEmojiPicker | boolean | Determines if the emoji panel needs to be shown or not |
setShowEmojiPicker | (status: boolean) => void | Method to update the emoji picker status |
uploadStatus | UploadStatus | Determines the upload progress status of the attachment message. |
uploadedFiles | File[] | Content of the attachments to be sent. |
setUploadedFiles | (uploadedFiles: File[]) => void | Method to update the content of attachments to be sent. |
Usage example of the app state:
- turnkey
- react-sdk
- web-sdk
import { useRecording } from "customization-api";
...
const { isRecordingActive, startRecording, stopRecording } = useRecording();
import { useRecording } from "@appbuilder/react";
...
const { isRecordingActive, startRecording, stopRecording } = useRecording();
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 | ( option: ChatOption, messageStatusCallback?: MessageStatusCallback ) => void | Method to send a message. |
deleteMessage | ( msgId: string, to?:string , chatType?: SDKChatType ) => 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 number 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 |
type | ChatMessageType | type of message |
thumb | string | thumbnail of the image message |
url | string | URL of the attachment message |
fileName | string | name of the attachment message |
ext | string | extension of the attachment message |
usage example of the app state:
- turnkey
- react-sdk
- web-sdk
import { useMessages } from "customization-api";
const {
groupMessages,
privateMessages,
sendMessage,
deleteMessage,
groupUnreadCount,
setGroupUnreadCount,
indIvidualUnreadCount,
setIndividualUnreadCount,
} = useMessages();
import { useMessages } from "@appbuilder/react";
const {
groupMessages,
privateMessages,
sendMessage,
deleteMessage,
groupUnreadCount,
setGroupUnreadCount,
indIvidualUnreadCount,
setIndividualUnreadCount,
} = useMessages();
import { useMessages } from "@appbuilder/web";
const {
groupMessages,
privateMessages,
sendMessage,
deleteMessage,
groupUnreadCount,
setGroupUnreadCount,
indIvidualUnreadCount,
setIndividualUnreadCount,
} = useMessages();
useVideoQuality() : videoQualityInterface
The Video Quality app state provides option to change the encoder resolution for video and screenShare profiles
videoQualityInterface
Here's the table for the properties related to video and screen share quality settings:
Key | Type | Description |
---|---|---|
currentVideoQuality | VideoEncoderConfigurationPreset | VideoEncoderConfiguration | The current video quality configuration. |
setVideoQuality | (videoQuality: VideoEncoderConfigurationPreset | VideoEncoderConfiguration) => void | Function to set the video quality configuration. |
currentScreenShareQuality | ScreenEncoderConfigurationPreset | VideoEncoderConfiguration | The current screen share quality configuration. |
setScreenShareQuality | (screenShareQuality: ScreenEncoderConfigurationPreset | VideoEncoderConfiguration) => void | Function to set the screen share quality configuration. |
videoEncoderPresets | VideoEncoderConfigurationPreset[] | An array of available video encoder presets. |
screenShareEncoderPresets | ScreenEncoderConfigurationPreset[] | An array of available screen share encoder presets. |
usage example of the app state:
- turnkey
- react-sdk
- web-sdk
import { useVideoQuality } from "customization-api";
const { setVideoQuality, setScreenShareQuality } = useVideoQuality();
const videoEncoderConfig = {
width: 960,
height: 720,
frameRate: 30,
bitRateMax: 1380,
bitRateMin: 800,
};
setScreenShareQuality(videoEncoderConfig);
// setScreenShareQuality('480p_1')
setVideoQuality("720p_3");
import { useVideoQuality } from "@appbuilder/react";
const { setVideoQuality, setScreenShareQuality } = useVideoQuality();
const videoEncoderConfig = {
width: 960,
height: 720,
frameRate: 30,
bitRateMax: 1380,
bitRateMin: 800,
};
setScreenShareQuality(videoEncoderConfig);
// setScreenShareQuality('480p_1')
setVideoQuality("720p_3");
import { useVideoQuality } from "@appbuilder/web";
const { setVideoQuality, setScreenShareQuality } = useVideoQuality();
const videoEncoderConfig = {
width: 960,
height: 720,
frameRate: 30,
bitRateMax: 1380,
bitRateMin: 800,
};
setScreenShareQuality(videoEncoderConfig);
// setScreenShareQuality('480p_1')
setVideoQuality("720p_3");
useVirtualBackground(): virtualBackgroundInterface
The Virtual Background app state that governs the ui for virtual background.
virtualBackgroundInterface
Key | Type | Description |
---|---|---|
virtualBackgrounds | VBOption[] | An array of available virtual background options. |
addVirtualBackgrounds | (options: VBOption[]) => void | Function to add new virtual background options to the list. |
setVBPreview | (type: VBMode, path: string) => void | Function to set a preview of a virtual background. |
applyVirtualBackground | () => void | Function to apply the selected virtual background. |
isVirtualBackgroundPanelOpen | boolean | A boolean value that returns true if the virtual background panel is open, and false otherwise. |
hideVirtualBackgroundPanel | () => void | Function to hide the virtual background panel. |
showVirtualBackgroundPanel | () => void | Function to show the virtual background panel. |
usage example of the app state:
- turnkey
- react-sdk
- web-sdk
import { useVirtualBackground } from "customization-api";
const {
virtualBackgrounds,
addVirtualBackgrounds,
applyVirtualBackground,
setVBPreview,
} = useVirtualBackground();
import { useVirtualBackground } from "@appbuilder/react";
const {
virtualBackgrounds,
addVirtualBackgrounds,
applyVirtualBackground,
setVBPreview,
} = useVirtualBackground();
import { useVirtualBackground } from "@appbuilder/web";
const {
virtualBackgrounds,
addVirtualBackgrounds,
applyVirtualBackground,
setVBPreview,
} = useVirtualBackground();
useBeautyEffects(): BeautyEffectInterface
The Beauty Effects app state controls the application of image enhancement options.
BeautyEffectsInterface
Key | Type | Description |
---|---|---|
applyBeautyEffect | (config: BeautyEffects) => void | Function to apply the given beauty effects configuration. |
removeBeautyEffect | () => void | Function to remove the applied beauty effects. |
usage example of the app state:
- turnkey
- react-sdk
- web-sdk
import { useBeautyEffects } from "customization-api";
const { applyBeautyEffect } = useBeautyEffects();
applyBeautyEffect({
lighteningContrastLevel: 1,
rednessLevel: 0.5,
sharpnessLevel: 1,
lighteningLevel: 1,
smoothnessLevel: 1,
});
import { useBeautyEffects } from "@appbuilder/react";
const { applyBeautyEffect } = useBeautyEffects();
applyBeautyEffect({
lighteningContrastLevel: 1,
rednessLevel: 0.5,
sharpnessLevel: 1,
lighteningLevel: 1,
smoothnessLevel: 1,
});
import { useBeautyEffects } from "@appbuilder/web";
const { applyBeautyEffect } = useBeautyEffects();
applyBeautyEffect({
lighteningContrastLevel: 1,
rednessLevel: 0.5,
sharpnessLevel: 1,
lighteningLevel: 1,
smoothnessLevel: 1,
});
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.
You can add custom content objects to the render app state using the 'AddCustomContent' action in dispatch
Usage example of the app state:
- turnkey
- react-sdk
- web-sdk
import { useContent } from "customization-api";
...
const { defaultContent, activeUids } = useContent();
import { useContent } from "@appbuilder/react";
...
const { defaultContent, activeUids } = useContent();
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
- react-sdk
- web-sdk
import { useLocalUserInfo } from "customization-api";
...
const {
uid,
audio,
video,
type,
streamType
name,
screenUid,
offline,
} = useLocalUserInfo();
import { useLocalUserInfo } from "@appbuilder/react";
...
const {
uid,
audio,
video,
type,
streamType
name,
screenUid,
offline,
} = useLocalUserInfo();
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
- react-sdk
- web-sdk
import { useLayout } from "customization-api";
...
const { currentLayout, setLayout } = useLayout();
import { useLayout } from "@appbuilder/react";
...
const { currentLayout, setLayout } = useLayout();
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
- react-sdk
- web-sdk
import { useRoomInfo } from "customization-api";
...
const { isJoinDataFetched, data } = useRoomInfo();
import { useRoomInfo } from "@appbuilder/react";
...
const { isJoinDataFetched, data } = useRoomInfo();
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
- react-sdk
- web-sdk
import { useUserName } from "customization-api";
...
const [userName, setUserName] = useUserName();
import { useUserName } from "@appbuilder/react";
...
const [userName, setUserName] = useUserName();
import { useUserName } from "@appbuilder/web";
...
const [userName, setUserName] = useUserName();
Returns:
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 |
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
- react-sdk
- web-sdk
import { useRtc } from "customization-api";
...
const { RtcEngineUnsafe, setDualStreamMode } = useRtc();
import { useRtc } from "@appbuilder/react";
...
const { RtcEngineUnsafe, setDualStreamMode } = useRtc();
import { useRtc } from "@appbuilder/web";
...
const { RtcEngineUnsafe, setDualStreamMode } = useRtc();