Store channel and user data

Signaling storage is a powerful feature that enables you to store and manage channel and user attributes in a serverless storage system. It acts as an extension of your database, offering synchronization across all participants. By using signaling storage, you can develop innovative, reliable, and scalable applications without the hassle of setting up your own database. This seamless integration ensures that data is readily available and up-to-date for all users, making it easier to build real-time and collaborative applications.

Your app receives metadata modification events in real-time enabling you to update the front-end accordingly. You can leverage user and channel metadata in Signaling apps to:

Maintain search history: Enable users to quickly search for specific messages, users, or topics within the app.
Customize notifications: Enable users to customize their notification settings, such as choosing notifications to receive and setting custom alert tones.
Enhance security: Enforce security measures, such as verifying user identity and encrypting messages.

Understand the tech

Using Signaling storage you associate metadata with a particular channel or a specific user:

Channel metadata: store and distribute contextual channel data in your app, such as props, announcements, member lists, and relationship chains. When channel properties are set, updated, or deleted by a user, an event notification is triggered, and other users in the channel receive this information within 100ms.
User metadata: store and distribute contextual data about users in your app. A user has one set of metadata with one or more attributes. When an attribute is set, updated or deleted, an event notification is triggered, and users who subscribe to this users metadata will receive this information within 100ms.

This section presents an overview of the steps required to integrate Signaling storage into your app. The following figure shows the basic workflow you implement to read and write channel and user metadata:

Signaling workflow

Prerequisites

To follow this page, you must have:

Setup the Signaling SDK reference app.

Implement storage

The following code examples show how to implement storage features in your Signaling app:

Set local user metadata

To set a key-value pair for the local user's metadata:

fun setUserMetadata(uid: Int, key: String, value: String) {
    // Create a metadata instance
    val metadata: Metadata = signalingEngine!!.storage!!.createMetadata()
    // Add a metadata item
    metadata.setMetadataItem(MetadataItem(key, value, -1))
    metadata.majorRevision = -1
    signalingEngine?.storage?.setUserMetadata(uid.toString(), metadata,
        MetadataOptions(true, true), object: ResultCallback<Void?> {
            override fun onSuccess(responseInfo: Void?) {
               notify("User metadata set successfully")
            }
            override fun onFailure(errorInfo: ErrorInfo) {
                notify("Failed to set user metadata: $errorInfo")
            }
        })
}

Update local user metadata

To update a value in the local user's metadata:

fun updateUserMetadata(uid: Int, key: String, value: String) {
    // Create a metadata instance
    val metadata: Metadata = signalingEngine!!.storage!!.createMetadata()
    // Add a metadata item
    metadata.setMetadataItem(MetadataItem(key, value, -1))
    signalingEngine?.storage?.updateUserMetadata(uid.toString(), metadata,
        MetadataOptions(true, true), object: ResultCallback<Void?> {
            override fun onSuccess(responseInfo: Void?) {
                notify("User metadata updated successfully")
            }
            override fun onFailure(errorInfo: ErrorInfo) {
                notify("Failed to update user metadata: $errorInfo")
            }
        })
}

updateUserMetadata

Retrieve a user's metadata

To get all the key-value pairs stored in a user's metadata:

fun getUserMetadata(uid: Int) {
    signalingEngine?.storage?.getUserMetadata(uid.toString(), object: ResultCallback<Metadata?> {
        override fun onSuccess(data: Metadata?) {
            val items = data?.metadataItems
            var summary = "User metadata\n"
            if (items != null) {
                for (item in items) {
                    summary += "${item.key}: ${item.value}\n"
                }
            }
            notify(summary)
        }
        override fun onFailure(errorInfo: ErrorInfo) {
            notify("Failed to get user metadata: $errorInfo")
        }
    })
}

getUserMetadata

To receive notifications of modifications to a user's data, you subscribe to the users metadata:

fun subscribeUserMetadata(uid: Int) {
    if (subscribedIds.contains(uid)) {
        return
    }
    signalingEngine?.storage?.subscribeUserMetadata(
        uid.toString(),
        object : ResultCallback<Void?> {
            override fun onSuccess(responseInfo: Void?) {
                notify("Subscribe user metadata success")
                subscribedIds.add(uid)
            }
            override fun onFailure(errorInfo: ErrorInfo) {
                notify(errorInfo.toString())
            }
        })
}

subscribeUserMetadata

Set channel metadata

To store a key-value pair in the channel's metadata:

fun setChannelMetadata(key: String, value: String, revision: Long, lockName: String) {
    // Create a metadata instance
    val metadata: Metadata = signalingEngine!!.storage!!.createMetadata()
    // Add a metadata item
    metadata.setMetadataItem(MetadataItem(key, value, revision))
    metadata.majorRevision = -1
    signalingEngine?.storage?.setChannelMetadata(channelName, channelType, metadata,
        MetadataOptions(true, true), lockName, object: ResultCallback<Void?> {
            override fun onSuccess(responseInfo: Void?) {
                notify("Channel metadata set successfully")
            }
            override fun onFailure(errorInfo: ErrorInfo) {
                notify("Failed to set channel metadata: $errorInfo")
            }
        })
}

setChannelMetadata

Retrieve channel metadata

To get all the key-value pairs stored in a channels's metadata:

fun getChannelMetadata() {
    signalingEngine?.storage?.getChannelMetadata(channelName, channelType, object: ResultCallback<Metadata?> {
        override fun onSuccess(data: Metadata?) {
            var summary = "Channel metadata\n"
            val items = data?.metadataItems
            if (items != null) {
                for (item in items) {
                    summary += "${item.key}: ${item.value}\n"
                }
            }
            notify(summary)
        }
        override fun onFailure(errorInfo: ErrorInfo) {
            notify(errorInfo.toString())
        }
    })
}

getChannelMetadata

Receive notification when a user's metadata is updated

To get notified of changes in a user's metadata, handle the event callback:

override fun onStorageEvent(storageEventArgs: StorageEvent) {
    // Your Storage Event handler
    when (storageEventArgs.storageType) {
        RtmConstants.RtmStorageType.CHANNEL -> {
            // channel metadata was updated
            showChannelMetadata(storageEventArgs.data)
        }
        RtmConstants.RtmStorageType.USER -> {
            // user metadata was updated
            showMessage(
                "Metadata event " +
                        storageEventArgs.eventType +
                        ", User: " +
                        storageEventArgs.target
            )
            //showUserMetadata(eventArgs.publisher, eventArgs.data.metadata);
        }
        else -> {
            showMessage("Storage event: ${storageEventArgs.eventType}")
        }
    }
}    
override fun onTopicEvent(eventArgs: TopicEvent) {
    // Your Topic Event handler
}
override fun onLockEvent(eventArgs: LockEvent) {
    // Your Lock Event handler
}

Event Listeners

Manage Locks

Locks enable you to safely share critical resources between different users and processes in a distributed system. To set, acquire, release, remove, revoke locks, and get locks information:

fun setLock (lockName: String, ttl: Long) {
    // ttl is the lock expiration time in case the user goes offline
    signalingEngine?.lock?.setLock(channelName, channelType, lockName, ttl, object: ResultCallback<Void?> {
        override fun onSuccess(responseInfo: Void?) {
            notify("Lock set successfully")
        }
        override fun onFailure(errorInfo: ErrorInfo) {
            notify(errorInfo.toString())
        }
    })
}
fun acquireLock(lockName: String, retry: Boolean) {
    signalingEngine?.lock?.acquireLock(channelName, channelType, lockName, retry, object: ResultCallback<Void?> {
        override fun onSuccess(responseInfo: Void?) {
            notify("Lock acquired successfully")
        }
        override fun onFailure(errorInfo: ErrorInfo) {
            notify(errorInfo.toString())
        }
    })
}
fun releaseLock(lockName: String, retry: Boolean) {
    signalingEngine?.lock?.releaseLock(channelName, channelType, lockName, object: ResultCallback<Void?> {
        override fun onSuccess(responseInfo: Void?) {
            notify("Lock released successfully")
        }
        override fun onFailure(errorInfo: ErrorInfo) {
            notify(errorInfo.toString())
        }
    })
}
fun removeLock(lockName: String) {
    signalingEngine?.lock?.releaseLock(channelName, channelType, lockName, object: ResultCallback<Void?> {
        override fun onSuccess(responseInfo: Void?) {
            notify("Lock released successfully")
        }
        override fun onFailure(errorInfo: ErrorInfo) {
            notify(errorInfo.toString())
        }
    })
}
fun getLocks() {
    signalingEngine?.lock?.getLocks(channelName, channelType, object: ResultCallback<ArrayList<LockDetail?>> {
        override fun onSuccess(lockDetail: ArrayList<LockDetail?>) {
            var summary = "Lock details:\n"
            for (lock in lockDetail) {
                if (lock != null) {
                    summary += "Lock: ${lock.lockName}, Owner:${lock.lockOwner}"
                }
            }
            notify(summary)
        }
        override fun onFailure(errorInfo: ErrorInfo) {
            notify(errorInfo.toString())
        }
    })
}

Lock

Test storage

This section explains how to run the Store channel and user data example in the reference app and test channel and user metadata features.

The example implements the following functionality. After a local user logs in to Signaling, they set their metadata in the form of key-value pairs. When the user modifies a value stored as metadata, they call the update method to save the new value. The app show a list of all users currently in the channel. When the local user selects another user from the list, the remote users metadata is retrieved and displayed. The local user subscribes to the metadata of remote users to be notified of any changes. The local user can set channel metadata using revision and lock features.

To test this functionality:

Configure the project
1. Open the file <samples-root>/signaling-manager/src/main/res/raw/config.json
2. Set appId to the AppID of your project.
3. Choose one of the following authentication methods:
  - Temporary token:
    1. Generate an RTM token using your uid.
    2. Set token to this value in config.json.
  - Authentication server:
    1. Setup an Authentication server
    2. In config.json, set:
      - token to an empty string.
      - serverUrl to the base URL for your token server. For example: https://agora-token-service-production-yay.up.railway.app.
Run the reference app
1. In Android Studio, connect a physical Android device to your development machine.
2. Click Run to start the app.
3. A moment later you see the project installed on your device.
Login to Signaling as a first user
1. Enter a numeric User ID and press Login to log in to Signaling.
2. Enter a Channel name and press Subscribe to subscribe to a channel. You see the following:
  1. Your User ID appears in the users list.
  2. You see all the key-value pairs previously saved to the channel metadata.
  3. You see notifications confirming update of user metadata.
Login to Signaling as another user
1. Launch another reference app instance, and log in using a different User ID. Enter the same channel name as before, and press Subscribe.
  
  You see that both User IDs appear in the user lists in both instances.
Test channel metadata

In either instance, type in a Key and the Value you wish to store in the channel metadata, then press Update. You see that the key-value pair is added or updated in the Channel Metadata in both instances.
Test version control
1. Under Set channel metadata, type a new Value for an existing channel metadata Key. Enter a random positive integer for Revision and press Update. The log events section shows that the storage operation fails due to outdated revision.
2. Update the Revision value to show the same number as displayed against the metadata key under Channel Metadata, then press Update again. This time, the operation succeeds.
Test locks
1. Under Manage Locks, type a Lock Name and press Set. You see a SET event notification confirming creation of the lock.
2. In Lock to apply, enter the same lock name and press Update. You see an error reporting that the lock has not been acquired.
3. Press Acquire. You see an ACQUIRED event notification confirming acquisition of the lock.
4. Press Update, this time the channel key value is updated under Channel Metadata.
5. Press Get. You see details of all current locks in the logs section.
6. Press Release to release the lock, and Remove to delete it.
Test user metadata
1. In the user bio box, type in some text and press Update Bio. You see user metadata UPDATE notifications in both instances.
2. In the other instance, select the user for which you modified the User bio. You see their updated metadata bio.

Reference

This section contains additional information that either supplements the content on this page or directs you to documentation that covers other aspects of this product.

You are viewing Agora Docs forBeta products and features. Switch to Docs