Session Store (Alpha)

Session store is a shared realtime key-value store that is accessible by everyone in the room. Consider it as additional data associated with the session at the top level. Session store can be utilized to implement features such as pinned text, spotlight (which brings a particular peer to the center stage for everyone in the room), and more.

The session store persists throughout the session and is cleared when the last peer leaves the room.

💡 Session Store vs Peer Metadata

While peer metadata is associated with individual peers and each peer can have their own metadata, session store remains the same for every peer in the room.

How to use

Session store is only available after user joins the session.

To obtain a reference to the session store, you need to override the func on(sessionStoreAvailable store: HMSSessionStore) function of the HMSUpdateListener protocol. Once you get the reference to the store you can save it in your app for accessing later.

Setting a value for a specific key

Use the set API to assign a value to a specific key. Once a value is assigned, it will be available for other peers in the room who are observing this key.

store.set("new value", forKey: "my key") { finalValue, error in if error == nil { print("Value was updated successfuly to: \(finalValue)") } }

Retrieving a value for a specific key

Retrieve the current value and receive updates

Most of the time the application is interested not just in a current value of a key but also any updates to that value. To obtain the initial value and receive updates, use the observeChanges API. It takes a list of keys to observe and a closure that will be called for initial value and every time an update is received.

store.observeChanges(forKeys: ["date", "time"]) { [weak self] key, value in switch key { case "date": self?.onDateUpdated(value as? String) case "time": self?.onTimeUpdated(value as? String) default: break } }

You can have multiple observers running concurrently.

Managing the lifecycle of observers

During the lifecycle of the app, you may need to subscribe and unsubscribe for value updates. To unsubscribe we first need to get the observer reference by passing a completion closure to the observeChanges API:

store.observeChanges(forKeys: ["key", "key2"], changeObserver: { [weak self] key, value in // ... update handling code }) { [weak self] observer, error in self?.observer = observer }

Later when the observer is no longer needed call store.removeObserver(observer) API to stop receiving update.

Retrieve the current value once

Use the object(forKey:completion) API if your application does not require updates for the key.

store.object(forKey: "my key") { value, error in if error == nil { print("Value was fetched successfuly: \(value)") } }

Limitations and workarounds in Alpha release

  • There is no permission support, which means anyone can read/write session metadata. If you want to restrict access to session metadata, you have to implement it at the app level logic.
  • Locks are required to ensure consistency of the data. If two peers update the data at the same time, it may result in a race condition where the last update overwrites the previous ones.


  • Max payload size for data can be 1KB.
  • Maximum 100 keys are supported with 64KB limit applied to all keys combined.
  • Metadata size for 64 KB also include the key size.

👀 For an example of how to implement pinned chat support using session store in an iOS app with the 100ms SDK, checkout our example project.

Have a suggestion? Recommend changes ->

Was this helpful?