룸 예약
RoomStore serves as the core room management module within AtomicXCore, providing comprehensive support for scheduled rooms. This section is a step-by-step guide to help you efficiently develop and integrate scheduled room features using RoomStore.Core Features
Schedule and Cancel Room Reservations: Any user can schedule a new room or cancel an existing scheduled room.
Update Scheduled Room Information: Modify scheduled room details such as room name, start time, and end time.
Retrieve Scheduled Room List: Obtain the list of all scheduled rooms associated with the current account.
Retrieve Scheduled Room Participant List: Fetch the participant list for a specific scheduled room.
Add or Remove Scheduled Room Participants: Add or remove users from an existing scheduled room.
Core Concepts
Core concepts in
RoomStore are summarized in the table below:Core Concept | Type | Core Responsibility & Description |
enum | Indicates the current status of a room: scheduled (scheduled status). running (in progress). | |
struct | Defines the main data structure for scheduled rooms, including start time, end time, participant list, and more. | |
struct | Represents the main data structure for managing room state and tracking user-related room information. Key properties: scheduledRoomList: Stores all scheduled rooms for the current account.scheduledRoomListCursor: Cursor for paginating the scheduled room list . | |
enum | Represents real-time events related to room activity, including those for scheduled rooms. | |
class | Central class for managing the entire room lifecycle. Use it to schedule rooms, retrieve scheduled room lists, and subscribe to real-time scheduled room events via roomEventPublisher. |
Implementation Steps
Step 1: Integrate the SDK
Follow the Integration Overview to integrate the AtomicXCore SDK into your project. Make sure you have also completed Login Implementation.
Step 2: Scheduled Room Features
1. Schedule a Room
Implementation Workflow
1.1 Configure Scheduled Room Parameters: Use
ScheduleRoomOptions to set up the room name, password, start and end times, participant list, and other details.1.2 Set Room Permissions: Configure permissions for all members, such as muting all participants or disabling video by default.
1.3 Schedule the Room: Call
RoomStore's scheduleRoom method to create the scheduled room.Sample Code
import AtomicXCoreimport Foundation// Schedule a roomfunc scheduleRoom() {let startTime = Int(Date().timeIntervalSince1970) + 60 * 15 // Start 15 minutes from nowlet endTime = startTime + 60 * 30 // 30-minute durationlet reminderSeconds = 60 * 5 // Reminder 5 minutes before start// Create scheduled room optionsvar options = ScheduleRoomOptions()options.roomName = "Room Name"options.scheduleStartTime = startTimeoptions.scheduleEndTime = endTimeoptions.reminderSecondsBeforeStart = reminderSecondsoptions.scheduleAttendees = ["user01", "user02", "user03"] // List of participant user IDsoptions.password = "Room Password" // Optional; "" means no passwordoptions.isAllMicrophoneDisabled = false // Allow microphones by defaultoptions.isAllCameraDisabled = false // Allow cameras by defaultoptions.isAllScreenShareDisabled = false // Allow screen sharing by defaultoptions.isAllMessageDisabled = false // Allow messaging by defaultRoomStore.shared.scheduleRoom(roomID: "roomID", options: options) { result inswitch result {case .success:print("Room scheduled successfully")case .failure(let error):print("Failed to schedule room: [Error Code: \(error.code)] \(error.message)")}}}
scheduleRoom Method Parameters
Parameter | Type | Required | Description |
roomID | String | Yes | Unique string identifier for the room. Length: 0–48 bytes. Use only numbers, English letters (case sensitive), underscores (_), and hyphens (-). Avoid spaces and Chinese characters. |
options | ScheduleRoomOptions | Yes | Configuration object for the room. |
completion | CompletionClosure | No | Callback that returns the scheduling result. Returns error code and message if scheduling fails. |
ScheduleRoomOptions Struct Details
Parameter | Type | Required | Description |
roomName | String | No | Room name (optional, defaults to ""). Length: 0–60 bytes. Supports Chinese, English, numbers, and special characters. |
password | String | No | Room password ("" means no password). Length: 0–32 bytes. Recommend 4–8 digit numbers for easier input. If set, users must enter the password to join. Do not store sensitive info in plain text. |
scheduleStartTime | Int | Yes | Scheduled start time (Unix timestamp in seconds). Must be greater than the current time. We recommend aligning to a future minute. Example: 1736164800 (2025-01-06 20:00:00). |
scheduleEndTime | Int | Yes | Scheduled end time (Unix timestamp in seconds). Must be greater than scheduleStartTime.Set based on expected duration, e.g., scheduleStartTime + 3600 for one hour. |
reminderSecondsBeforeStart | Int | No | Reminder time before the scheduled start (seconds). Used for system-triggered notifications. Recommended: 300 (5 min) or 900 (15 min) for local app notifications. |
scheduleAttendees | [String] | No | List of participant user IDs. The system will send invitations to these users. For details, see retrieving the participant list for scheduled rooms. |
isAllMicrophoneDisabled | Bool | No | Whether to mute all participants by default. true: Disabled. false: Not disabled (default). |
isAllCameraDisabled | Bool | No | Whether to disable all participant cameras by default. true: Disabled. false: Not disabled (default). |
isAllScreenShareDisabled | Bool | No | Whether to disable screen sharing for all participants. true: Disabled. false: Not disabled (default). |
isAllMessageDisabled | Bool | No | Whether to mute chat messages for all participants. true: Disabled. false: Not disabled (default). |
2. Cancel a Scheduled Room
To cancel a scheduled room, call the
cancelScheduledRoom method on RoomStore:import AtomicXCoreimport Foundation// Cancel scheduled roomfunc cancelScheduledRoom(roomID: String) {RoomStore.shared.cancelScheduledRoom(roomID: roomID) { result inswitch result {case .success:print("Room reservation cancelled successfully")case .failure(let error):print("Failed to cancel room reservation: [Error Code: \(error.code)] \(error.message)")}}}
3. Updating a Scheduled Room
To update a scheduled room’s name, start time, or end time, use
updateScheduledRoom on RoomStore:import AtomicXCoreimport Foundation// Update scheduled roomfunc updateScheduledRoom() {let newStartTime = Int(Date().timeIntervalSince1970) + 60 * 30 // New start: 30 min from nowlet newEndTime = newStartTime + 60 * 45 // New end: 45 min after startvar options = ScheduleRoomOptions()options.roomName = "Room Name"options.scheduleStartTime = newStartTimeoptions.scheduleEndTime = newEndTimevar modifyFlag: ScheduleRoomOptions.ModifyFlag = []modifyFlag.insert(.roomName)modifyFlag.insert(.scheduleStartTime)modifyFlag.insert(.scheduleEndTime)RoomStore.shared.updateScheduledRoom(roomID: "roomID", options: options, modifyFlag: modifyFlag) { result inswitch result {case .success:print("Scheduled room updated successfully")case .failure(let error):print("Failed to update scheduled room: [Error Code: \(error.code)] \(error.message)")}}}
updateScheduledRoom Method Parameters
Parameter | Type | Required | Description |
roomID | String | Yes | Unique string identifier for the room. Length: 0–48 bytes. Use only numbers, English letters (case sensitive), underscores (_), and hyphens (-). Avoid spaces and Chinese characters. |
options | ScheduleRoomOptions | Yes | Configuration object for the scheduled room. See details in ScheduleRoomOptions struct. |
modifyFlag | ScheduleRoomOptions.ModifyFlag | Yes | Flags indicating which room properties to update. Only supports updating room name, start time, and end time. See details in ScheduleRoomOptions.ModifyFlag. |
completion | CompletionClosure | No | Callback that returns the result of the update. Returns error code and message if the update fails. |
ScheduleRoomOptions.ModifyFlag Details
Parameter | Type | Description |
roomName | UInt | Use this flag when updating the scheduled room name. You must also set the roomName field in ScheduleRoomOptions. |
scheduleStartTime | UInt | Use this flag when updating the scheduled room start time. You must also set the scheduleStartTime field in ScheduleRoomOptions. |
scheduleEndTime | UInt | Use this flag when updating the scheduled room end time. You must also set the scheduleEndTime field in ScheduleRoomOptions. |
4. Add or Remove Participants
To add or remove participants from a scheduled room, use the
addScheduledAttendees or removeScheduledAttendees methods on RoomStore:import AtomicXCoreimport Foundation// Add participantsfunc addScheduledAttendees(roomID: String, userIDList: [String]) {RoomStore.shared.addScheduledAttendees(roomID: roomID, userIDList: userIDList) { result inguard let self = self else { return }switch result {case .success:print("Scheduled participants added successfully")case .failure(let error):print("Failed to add scheduled participants: [Error Code: \(error.code)] \(error.message)")}}}// Remove participantsfunc removeScheduledAttendees(roomID: String, userIDList: [String]) {RoomStore.shared.removeScheduledAttendees(roomID: roomID, userIDList: userIDList) { result inswitch result {case .success:print("Scheduled participants removed successfully")case .failure(let error):print("Failed to remove scheduled participants: [Error Code: \(error.code)] \(error.message)")}}}
Step 3: Retrieving the Scheduled Room List
To obtain all scheduled rooms for the current account, call the
getScheduledRoomList method. Paging is supported via the cursor parameter.import AtomicXCoreimport Foundation// Retrieve scheduled room listfunc getScheduledRoomList(cursor: String? = nil) {// 'cursor' is a pagination cursor. Pass nil for the first call; use the previous nextCursor for subsequent pages.RoomStore.shared.getScheduledRoomList(cursor: cursor) { result inswitch result {case .success(let (roomList, nextCursor)):print("Scheduled room list retrieved successfully")case .failure(let error):print("Failed to retrieve scheduled room list: [Error Code: \(error.code)] \(error.message)")}}}
Step 4: Retrieve Participants for a Scheduled Room
To retrieve the participant list for a specific scheduled room, use the
getScheduledAttendees method. Paging is supported via the cursor parameter.import AtomicXCoreimport Foundation// Retrieve participant list for a scheduled roomfunc getScheduledAttendees(roomID: String, cursor: String? = nil) {// 'cursor' is a pagination cursor. Pass nil for the first call; use the previous nextCursor for subsequent pages.RoomStore.shared.getScheduledAttendees(roomID: roomID, cursor: cursor) { result inswitch result {case .success(let (attendees, nextCursor)):print("Scheduled room participants retrieved successfully")case .failure(let error):print("Failed to retrieve scheduled room participants: [Error Code: \(error.code)] \(error.message)")}}}
Step 5: Subscribe to Real-Time Scheduled Room Events and State Changes
Subscribe to passive events related to scheduled rooms using
RoomEvent:import AtomicXCoreimport Foundationimport Combineprivate var cancellableSet = Set<AnyCancellable>()/// Subscribe to scheduled room eventsprivate func subscribeScheduledRoomEvents() {RoomStore.shared.roomEventPublisher.receive(on: DispatchQueue.main).sink { event inswitch event {case .onAddedToScheduledRoom(let roomInfo):print("Added to scheduled room. Room info: \(roomInfo)")case .onRemovedFromScheduledRoom(let roomInfo, let operatorUser):print("Removed from scheduled room. Room info: \(roomInfo), removed by: \(operatorUser)")case .onScheduledRoomCancelled(let roomInfo, let operatorUser):print("Scheduled room cancelled. Room info: \(roomInfo), cancelled by: \(operatorUser)")case .onScheduledRoomStartingSoon(let roomInfo):print("Scheduled room starting soon. Room info: \(roomInfo)")default:// Handle other non-scheduled room eventsbreak}}.store(in: &cancellableSet)}
Subscribe to changes in the scheduled room list state using
RoomState:import AtomicXCoreimport Foundationimport Combineprivate var cancellableSet = Set<AnyCancellable>()/// Subscribe to scheduled room list state changesprivate func subscribeScheduledRoomListState() {RoomStore.shared.state.subscribe(StatePublisherSelector(keyPath: \.scheduledRoomList)).receive(on: DispatchQueue.main).sink { scheduledRoomList inprint("Scheduled room list changed. Room list info: \(scheduledRoomList)")}.store(in: &cancellableSet)}
API Documentation
Store/Component | Feature Description | API Documentation |
RoomStore | Complete room lifecycle management: create & join / join / leave / end room / update & retrieve room info / schedule rooms / invite users outside the room / listen for passive in-room events (such as room deletion, info updates, etc.) |
FAQs
Why am I not receiving the onScheduledRoomStartingSoon event from RoomEvent after scheduling a room?
If you are not receiving a "room starting soon" notification after scheduling, check the following:
1. Verify Reminder Parameter (
reminderSecondsBeforeStart)The
onScheduledRoomStartingSoon event depends on the reminderSecondsBeforeStart property in ScheduleRoomOptions.By default, this property is 0, which disables the reminder.
To enable reminders, set this parameter explicitly when scheduling the room. The value is in seconds and determines how long before the start time the event is triggered.
2. Check the Scheduling Logic
The event will only be triggered if the following condition is met: scheduled start time (
scheduleStartTime) - current time > reminder offset (reminderSecondsBeforeStart).If the room's start time is too close (e.g., 5 minutes away) and the reminder is set too far in advance (e.g., 10 minutes before), the event will not trigger.
Make sure the scheduled start time is at least as far in the future as the reminder value you set.
Contact Us
For questions or feedback during integration or usage, contact info_rtc@tencent.com.
