Session Store

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.

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 void onSessionStoreAvailable({HMSSessionStore? hmsSessionStore}) function of the HMSUpdateListener protocol. Once you get the reference to the store you can save it in your app for accessing later.

class Meeting implements HMSUpdateListener{

    ... 

    ///[_hmsSessionStore] : This instance will be used in future to access any session metadata methods
    HMSSessionStore? _hmsSessionStore;

    ///Here we get the instance of HMSSessionStore using which
    ///we will be performing the session metadata actions
    @override
    void onSessionStoreAvailable({HMSSessionStore? hmsSessionStore}) {
        _hmsSessionStore = hmsSessionStore;
    }

    ...

}

Setting a value for a specific key

Use the setSessionMetadataForKey method 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.

class Meeting implements HMSUpdateListener, HMSActionResultListener{

  ...

    void setSessionMetadata({required String key, dynamic metadata}) {
       ///[key]: String key for the session metadata
      ///[metadata]: dynamic data for the key which you wish to set as session metadata
      ///[hmsActionResultListener]: an instance of a class which implements HMSActionResultListener
      ///Here this is an instance of a class that implements HMSActionResultListener, that is, Meeting

    _hmsSessionStore?.setSessionMetadataForKey(
        key: key, data: metadata, hmsActionResultListener: this);
    }

  ...

}

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 addKeyChangeListener method. It takes a list of keys to observe and a HMSKeyChangeListener instance that will be called for initial value and every time an update is received.

class Meeting implements HMSUpdateListener, HMSActionResultListener,HMSKeyChangeListener{

    ...

    HMSSessionStore? _hmsSessionStore;

    void addKeyListener(List<String> keysToBeListened){
        
        ///[keysToBeListened]: List of String containing the session keys which are needed to be listened
        ///[hmsKeyChangeListener]: an instance of a class which implements HMSKeyChangeListener
        ///Here this is an instance of a class that implements HMSKeyChangeListener, that is, Meeting

        _hmsSessionStore?.addKeyChangeListener(keys: keysToBeListened,hmsKeyChangeListener: this);
    }

    ...
}

You can have multiple key change listeners running concurrently.

Stop listening to updates for keys

To stop receiving updates on key values, especially in cases like when you leave the room, you can utilize the removeKeyChangeListener method.

class Meeting implements HMSUpdateListener, HMSActionResultListener,HMSKeyChangeListener{

    ...

    ///[hmsKeyChangeListener]: an instance of a class which implements HMSKeyChangeListener which was passed
    ///in addKeyChangeListener method while adding the key change listener
    ///Here this is an instance of a class that implements HMSKeyChangeListener, that is, Meeting
    _hmsSessionStore?.removeKeyChangeListener(hmsKeyChangeListener: this);

    ...

}

Retrieve the current value once

If you want to obtain session metadata without any subsequent updates, you can utilize the getSessionMetadataForKey method, which can be viewed as a getter method for session metadata.

class Meeting implements HMSUpdateListener, HMSActionResultListener,HMSKeyChangeListener{

    void getSessionMetadata(String key) async {
        ///[key]: key for which you wish to get the metadata
        ///This method returns a dynamic object that can be a String in case of success
        ///or can be an HMSException object in case of failure

        dynamic sessionMetadata = await _hmsSessionStore?.getSessionMetadataForKey(key: key);
        if (result is HMSException) {
            // Show the corresponding error
        }
        if (result != null) {
            // You can find the session metadata value in sessionMetadata variable
        }
    }
}

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.

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

Limits

• 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.

Migrating from older HMSSDK version to 1.6.0 or above for using session store

With the introduction of session store, HMSUpdateListener has undergone some changes. One notable addition is the onSessionStoreAvailable callback, which enables developers to implement session store functionality in their apps. This callback is particularly useful because it is triggered when the session store becomes available, allowing developers to retrieve and manage the data stored within it.

hmssdk_flutter: ^1.6.0

class Meeting implements HMSUpdateLister{


    //We will be storing the HMSSessionStore instance in _hmsSessionStore variable for future usages.
    //This instance can be shared with other classes as well.
    HMSSessionStore? _hmsSessionStore;
    ...

    ///Here we get the instance of HMSSessionStore using which
    ///we will be performing the session metadata actions
    @override
    void onSessionStoreAvailable({HMSSessionStore? hmsSessionStore}) {
        _hmsSessionStore = hmsSessionStore;
    }

    ...
}

That's it. You are all set to use Session Store.

Spotlight a peer

In large video conferences or webinars where numerous participants are present, spotlighting helps draw attention to a speaker, presenter, or panelist. By highlighting their video feed, it ensures that their message or presentation remains front and center, reducing distractions and maximizing engagement.

Let's see we can spotlight a peer using HMSSessionStore

class Meeting implements HMSUpdateListener, HMSActionResultListener,HMSKeyChangeListener{

...

/// Here [_hmsSessionStore] is an instance of HMSSessionStore
/// Details about how to get this are mentioned above

///Setting key as spotlight and data as peer's audio track Id
///[hmsActionResultListener] is an instance of class implementing HMSActionResultListener
_hmsSessionStore?.setSessionMetadataForKey(
        key: 'spotlight', data: audioTrackId, hmsActionResultListener: this);

...

}

class Meeting implements HMSUpdateListener, HMSActionResultListener,HMSKeyChangeListener{

  ...

  @override
  void onKeyChanged({required String key, required String? value}) {
    switch (key) {
      case 'spotlight':
        //Set the peer to spotlight here
        break;
      default:
        break;
    }
  }

  ...
}

class Meeting implements HMSUpdateListener, HMSActionResultListener,HMSKeyChangeListener{

/// Here [_hmsSessionStore] is an instance of HMSSessionStore
/// Details about how to get this are mentioned in above docs: https://www.100ms.live/docs/flutter/v2/how-to-guides/interact-with-room/room/session-store

///Setting key as spotlight and data as null
///[hmsActionResultListener] is an instance of class implementing HMSActionResultListener
_hmsSessionStore?.setSessionMetadataForKey(
        key: 'spotlight', data: null, hmsActionResultListener: this);

}

Checkout spotlight in action:

https://github.com/100mslive/100ms-flutter/assets/93931528/0a9df0b9-8518-4ca4-8cd3-7447a450acb8