Realtime Store - iOS

The Realtime Store allows you to store, update, retrieve, and observe custom key-value data within a room — in real time. It acts as a shared data layer across all connected participants, ensuring synchronized states throughout the session.

This is particularly useful for collaborative or stateful room experiences such as:

• Pinned messages and flags
• Moderation data (e.g., blocked users)
• Collaborative notes or polls

setValue()

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

Key Notes

• Supports String values only.
• Each key can store up to 1 KB of data.
• A maximum of 100 keys are allowed per session.
• Deletion is performed by setting the value to nil.
• Throws a VideoSDKError if:
  • You call it before joining the room (ERROR_ACTION_PERFORMED_BEFORE_ROOM_JOINED) or while the room is reconnecting (ERROR_ROOM_RECONNECTING).
  • The value is larger than 1 KB (ERROR_PAYLOAD_TOO_LARGE).
  • The request fails.
  • The session exceeds the 100-key limit.

Parameters

• key (String)
  The unique key to store the data under.

• value (String?)
  The string value to be stored. Pass nil to delete the key.

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

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

Key Notes

• Returns the current string value for the given key.
• Useful for fetching shared state when joining a room or reloading a view.
• Throws an error if the request fails, including 4046 (FAILED_TO_GET_VALUE) when the key is not set or was cleared.

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.

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

The observe() method subscribes to real-time updates for a given key. When the key’s value changes, onValueChanged(key:value:updatedBy:) is called on every listener observing that key, on the main queue.

Key Notes

• You register a listener object that conforms to the RealtimeStoreEventListener protocol.
• The first listener for a key subscribes to it on the server. If that fails, observe() throws and the listener is not added.
• The delegate method receives the new value and the Participant who updated it, or nil if that participant has already left.
• Ideal for syncing live data like timers, shared notes, or agendas.

Parameters

• key (String) The key to observe.

• listener (RealtimeStoreEventListener) An object that conforms to the RealtimeStoreEventListener protocol to receive updates.

Example

First, conform to the RealtimeStoreEventListener protocol:

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

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

Stops receiving updates for a specific key and listener combination.

Key Notes

• Call it when you no longer need updates for the key, before you leave the room. After you leave, it throws ERROR_ACTION_PERFORMED_BEFORE_ROOM_JOINED.

Parameters

• key (String) The key you want to stop observing.

• listener (RealtimeStoreEventListener) The listener that should stop receiving updates.

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)")
    }
}

---

Error Handling & Constraints

Property	Description
Error Handling	All RealtimeStore methods are async throws; wrap them in do-try-catch. They throw a VideoSDKError with code, name and message. Most failures are also reported through onError(error:).
Payload Size	Maximum 1 KB per key.
Supported Type	Only String values are supported. Use nil to delete key.
Concurrency	The latest write overwrites previous values (last write wins)
Key Limit	A maximum of 100 keys are allowed in a single session.

API Reference

The API references for all the methods utilized in this guide are provided below:

• setValue()
• getValue()
• observe()
• stopObserving()