RealtimeStore – iOS

The RealtimeStore, a property of the Room class, allows you to set, get, and listen to value changes for specific keys shared across all participants in a room.

It provides a simple key–value storage system that stays synchronized in real time among all connected participants.

All RealtimeStore methods are async throws. Call them with try await from a Task or another async context, after you have joined the room.

---

Methods

setValue()

func setValue(key: String, value: String?) async throws

The setValue() method is used to store or update data in the Realtime Store. If a key already exists, it will be overwritten with the new value. Passing nil as the value deletes the key.

Parameters

• key (String) – The unique key under which the data will be stored.
• value (String?) – The value to be stored. Pass nil to delete the key.

Throws

• ERROR_ROOM_RECONNECTING (3065) while the room is reconnecting.
• ERROR_ACTION_PERFORMED_BEFORE_ROOM_JOINED (3035) before you join the room.
• ERROR_PAYLOAD_TOO_LARGE (3072) if the value is larger than 1 KB (1024 bytes).
• FAILED_TO_SET_VALUE (4045) if the server refuses the request, for example when the session already has 100 keys. The error message gives the reason.
• Another VideoSDKError if the request fails due to network or internal issues.

Failures other than ERROR_ROOM_RECONNECTING and ERROR_PAYLOAD_TOO_LARGE are also sent to onError.

Example

let REALTIME_STORE_KEY = "Blocked_Students"
Task {
    do {
        try await room?.realtimeStore.setValue(key: REALTIME_STORE_KEY, value: "[Deep, Lily]")
        print("Data set successfully!")
    } catch {
        print("Failed to set data: \(error)")
    }
}

---

getValue()

func getValue(key: String) async throws -> String?

The getValue() method retrieves the current value associated with a given key from the Realtime Store.

Parameters

• key (String) – The key whose value you want to retrieve.

Returns

• String? — The stored value, or nil when the server answers with no value. A key that is not set throws 4046.

Throws

• ERROR_ROOM_RECONNECTING (3065) while the room is reconnecting.
• ERROR_ACTION_PERFORMED_BEFORE_ROOM_JOINED (3035) before you join the room.
• FAILED_TO_GET_VALUE (4046) if the key is not set or was cleared, or the server otherwise refuses the request. The error message gives the reason.
• Another VideoSDKError if the request fails due to network or internal issues.

Failures other than ERROR_ROOM_RECONNECTING are also sent to onError.

Example

let REALTIME_STORE_KEY = "Blocked_Students"
Task {
    do {
        let value = try await room?.realtimeStore.getValue(key: REALTIME_STORE_KEY)
        let displayValue = value ?? "nil (no value)"
        print("Current value: \(displayValue)")
    } catch {
        // A key that is not set throws 4046 (FAILED_TO_GET_VALUE)
        print("Failed to get data: \(error)")
    }
}

---

observe()

func observe(key: String, listener: RealtimeStoreEventListener) async throws

The observe() method subscribes to real-time updates for a given key. When the value of that key changes, the delegate method on your listener is triggered automatically for all participants. The SDK holds the listener weakly, so pass a class instance that you keep alive, such as your view controller.

Parameters

• key (String) – The key to observe for changes.
• listener (RealtimeStoreEventListener) – An object that conforms to the RealtimeStoreEventListener protocol.

Throws

• ERROR_ROOM_RECONNECTING (3065) while the room is reconnecting.
• ERROR_ACTION_PERFORMED_BEFORE_ROOM_JOINED (3035) before you join the room.
• ERROR_INVALID_PARAMETER (3073) if the key is empty.

The reconnecting and before-join errors are also sent to onError.

The first listener for a key subscribes to it on the server. If that subscribe fails, observe() throws the error, also sends it to onError, and does not add the listener. The subscription survives a reconnect or room switch.

Example

First, conform to the RealtimeStoreEventListener protocol. onValueChanged(key:value:updatedBy:) receives the key, the new value (nil when the key was deleted) and the Participant who made the change (nil when that participant has already left):

extension RoomViewController: RealtimeStoreEventListener {
    func onValueChanged(key: String, value: String?, updatedBy: Participant?) {
        print("RealtimeStore Value Changed - Key: \(key), Value: \(value ?? "nil"), UpdatedBy: \(updatedBy?.id ?? "-")")
    }
}

Then, start observing:

let REALTIME_STORE_KEY = "Blocked_Students"
Task {
    do {
        try await room?.realtimeStore.observe(key: REALTIME_STORE_KEY, listener: self)
        print("Started observing key successfully!")
    } catch {
        print("Failed to observe key: \(error)")
    }
}

---

stopObserving()

func stopObserving(key: String, listener: RealtimeStoreEventListener) async throws

The stopObserving() method stops receiving updates for a previously observed key for a specific listener.

Parameters

• key (String) – The key to stop observing.
• listener (RealtimeStoreEventListener) – The listener to remove.

Throws

• ERROR_ROOM_RECONNECTING (3065) while the room is reconnecting.
• ERROR_ACTION_PERFORMED_BEFORE_ROOM_JOINED (3035) before you join the room.

These errors are also sent to onError.

Example

let REALTIME_STORE_KEY = "Blocked_Students"
Task {
    do {
        try await room?.realtimeStore.stopObserving(key: REALTIME_STORE_KEY, listener: self)
        print("Stopped observing successfully!")
    } catch {
        print("Failed to stop observing: \(error)")
    }
}

---