Realtime Store - Android

The Realtime Store is a key-value store shared by everyone in the room. Any participant can set, read and observe a key, and every observer is told when its value changes. Use it through room.realtimeStore.

Typical uses:

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

setValue()

setValue() stores a value under a key. An existing value is overwritten. Passing null as the value deletes the key.

Key Notes

• setValue() is a suspend function. Call it from a coroutine.
• Supports String values only.
• Each key can store up to 1 KB of data (1024 bytes in UTF-8).
• A maximum of 100 keys are allowed per session.
• Deletion is performed by setting the value to null.
• Everyone observing the key, including you, receives the new value in onValueChanged().
• Throws a VideoSDKException if:
  • The room is not joined (3035) or is reconnecting (3065).
  • The value is larger than 1 KB (3072).
  • The server refuses the request (4045).
  • The request times out (3079). The value may still have been stored.

Parameters

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

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

Returns

Nothing. Read the stored value in onValueChanged() or with getValue().

Example

lifecycleScope.launch {
    try {
        room.realtimeStore.setValue("YOUR_KEY", message)
    } catch (e: VideoSDKException) {
        Log.e("VideoSDK", "Error: ${e.code} ${e.message}")
    }
}

---

getValue()

getValue() reads the current value of a key.

Key Notes

• getValue() is a suspend function. Call it from a coroutine.
• Returns the current string value for the given key, or null when the server answers with no value.
• Useful for fetching shared state when joining a room or reloading a view.
• Throws a VideoSDKException if the room is not joined (3035) or is reconnecting (3065), if the key is not set or was cleared (4046, FAILED_TO_GET_VALUE), or if the request times out (3079).

Parameters

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

Returns

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

Example

lifecycleScope.launch {
    try {
        val value: String? = room.realtimeStore.getValue("YOUR_KEY")
        Log.d("VideoSDK", "Value: $value")
    } catch (e: VideoSDKException) {
        Log.e("VideoSDK", "Error: ${e.code} ${e.message}")
    }
}

---

observe()

observe() watches a key. Each time its value changes, onValueChanged() is called on your listener.

Key Notes

• You register a listener object that implements the RealtimeStoreListener interface.
• onValueChanged() receives the new value and the Participant who updated it. The participant is null when the writer has left or was never seen. A deleted key arrives as null.
• You only get changes made after the subscription reaches the server, so a change made right after observe() can be missed. To read the current value, call getValue().
• observe() is a regular function, not a suspend function. Called before the room is joined, or while it is reconnecting, it adds no listener and reports 3035 or 3065 on onError().
• Registering the same listener for the same key twice is ignored. An empty key throws IllegalArgumentException.
• If the server refuses to watch the key, onError() reports 4085 (FAILED_TO_OBSERVE_VALUE).

Parameters

• key (String)
  The key to observe.

• listener (RealtimeStoreListener)
  The listener whose onValueChanged() is called with the new String? value (null when the key was deleted) and the Participant? who updated the value.

Example

val realtimeStoreListener = object : RealtimeStoreListener {
  override fun onValueChanged(newValue: String?, updatedBy: Participant?) {
      // newValue is null when the key was deleted
      // updatedBy is null when the writer has left or was never seen
      Log.d("VideoSDK", "onValueChange: Received update from: ${updatedBy?.displayName}")
      Log.d("VideoSDK", "onValueChange: Received update from: ${updatedBy?.id}")
      Log.d("VideoSDK", "onValueChange: New Value -> $newValue")
  }
}

room.realtimeStore.observe(KEY_CHAT_HISTORY, realtimeStoreListener)

---

stopObserving()

Stops receiving updates for a specific key and listener combination.

Key Notes

• Should be called when the listener is no longer needed (e.g., when the activity or fragment is destroyed).
• It works whether or not the room is joined, and it never reports an error.

Parameters

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

• listener (RealtimeStoreListener)
  The listener that will be removed from the list of listeners.

Example

room.realtimeStore.stopObserving("YOUR_KEY", realtimeStoreListener)

---

Error Handling & Constraints

Property	Description
Error Handling	setValue() and getValue() throw VideoSDKException. 3035, server refusals (4045, 4046) and timeouts (3079) are also reported on onError(). observe() reports 3035 / 3065 on onError() instead of throwing, and throws IllegalArgumentException for an empty key.
Payload Size	Maximum 1 KB per key.
Supported Type	Only String values are supported. Use null 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 this page are provided below.

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