Skip to main content

You are viewing Agora Docs forBetaproducts and features. Switch to Docs

Android
iOS
macOS
Web
Linux C++
Unity

Store user metadata

The Signaling storage service enables you to store and share contextual user data in your app, such as name, date-of-birth, avatar, and connections. When user metadata is set, updated, or deleted, the SDK triggers a storage event notification. Other users in the channel receive this notification within 100ms and use the information according to your business logic.

Understand the tech

Use metadata enables you to store and share user level information. A set of user metadata facilitates business-level data storage and real-time notifications. Each user has only one set of user metadata, but each set may contain multiple metadata items. For relevant restrictions, refer to the API usage restrictions. Each metadata item has key, value, and revision properties.

User metadata is stored permanently in the Signaling database. The data persists even after a user logs out. You must explicitly delete it to remove it from the database. This feature impacts your storage billing. Refer to Pricing for details.

Prerequisites

Ensure that you have integrated the Signaling SDK in your project and implemented the framework functionality from the SDK quickstart page.

Implement user metadata storage

The section shows you to implement user metadata storage in your Signaling app.

Set user metadata

To create a new metadata item for the user, or to update the value of am existing item, call setUserMetadata. This method creates a new item in the user metadata if the specified key does not exist, or overwrites the associated value if a metadata item with the specified key already exists.

The following example saves a set of metadata items for a specified user. It configures the options parameter to add timestamp and modifier information to each metadata item.


_20
Metadata metadata = new Metadata();
_20
metadata.getItems().add(new MetadataItem("Name", "Tony"));
_20
metadata.getItems().add(new MetadataItem("Age", "40"));
_20
metadata.getItems().add(new MetadataItem("Avatar", "https://your-domain/avatar/tony.png"));
_20
_20
MetadataOptions options = new MetadataOptions();
_20
options.setRecordTs(true);
_20
options.setRecordUserId(true);
_20
_20
mRtmClient.getStorage().setUserMetadata("Tony", metadata, options, new ResultCallback<Void>() {
_20
@Override
_20
public void onSuccess(Void responseInfo) {
_20
log(CALLBACK, "Set user metadata success");
_20
}
_20
_20
@Override
_20
public void onFailure(ErrorInfo errorInfo) {
_20
log(ERROR, "Failed to set user metadata: " + errorInfo.toString());
_20
}
_20
});

The onSuccess callback notifies you of the successful completion of the storage operation. Additionally, Signaling triggers an onStorageEvent notification of event type UPDATE within 100 ms to inform all users who have subscribed to the this user's metadata.

Get user metadata

To retrieve all metadata items associated with a specific user, call getUserMetadata. Refer to the following example:


_15
mRtmClient.getStorage().getUserMetadata("Tony", new ResultCallback<Metadata>() {
_15
@Override
_15
public void onSuccess(Metadata data) {
_15
log(CALLBACK, "Get user metadata success");
_15
log(INFO, "Major revision: " + data.getMajorRevision());
_15
for (MetadataItem item : data.getItems()) {
_15
log(INFO, item.toString());
_15
}
_15
}
_15
_15
@Override
_15
public void onFailure(ErrorInfo errorInfo) {
_15
log(ERROR, "Failed to get user metadata: " + errorInfo.toString());
_15
}
_15
});

You can also leave the userId parameter blank to get the local user's metadata:


_11
mRtmClient.getStorage().getUserMetadata("", new ResultCallback<Metadata>() {
_11
@Override
_11
public void onSuccess(Metadata data) {
_11
log(CALLBACK, "Get user metadata success");
_11
}
_11
_11
@Override
_11
public void onFailure(ErrorInfo errorInfo) {
_11
log(ERROR, errorInfo.toString());
_11
}
_11
});

Signaling SDK returns the following data structure:


_26
{
_26
majorRevision: 734874892,
_26
metadata:{
_26
{
_26
key:"Name",
_26
value:"Tony",
_26
revision:734874872,
_26
updateTs:1688978391900,
_26
authorUid:"Tony"
_26
},
_26
{
_26
key:"Age",
_26
value:"40",
_26
revision:734874862,
_26
updated:1688978390900,
_26
authorUid:"Tony"
_26
},
_26
{
_26
key:"Avatar",
_26
value:"https://your-domain/avatar/tony.png",
_26
revision:734874812,
_26
updated:1688978382900,
_26
authorUid:"Tony"
_26
}
_26
}
_26
}

Update user metadata

To modify existing metadata items, call updateUserMetadata. If the metadata item does not exist, the SDK returns an error. This method is useful for business scenarios that require permission control on creating new metadata items. For example, the admin defines the user metadata fields and users may only update the values.

The following example updates the value of an existing metadata item:


_14
Metadata metadata = new Metadata();
_14
metadata.getItems().add(new MetadataItem("Age", "45"));
_14
_14
mRtmClient.getStorage().updateUserMetadata("Tony", metadata, new MetadataOptions(true, true), new ResultCallback<Void>() {
_14
@Override
_14
public void onSuccess(Void responseInfo) {
_14
log(CALLBACK, "update user metadata success");
_14
}
_14
_14
@Override
_14
public void onFailure(ErrorInfo errorInfo) {
_14
log(ERROR, errorInfo.toString());
_14
}
_14
});

The onSuccess callback notifies you of the successful completion of the storage operation. Additionally, Signaling triggers an onStorageEvent notification of event type UPDATE within 100 ms to inform all users who have subscribed to the this user's metadata.

Delete user metadata

To delete metadata items that are no longer required, call removeUserMetadata. Refer to the following sample code:


_16
Metadata metadata = new Metadata();
_16
MetadataItem age = new MetadataItem();
_16
age.setKey("Age");
_16
metadata.getItems().add(age);
_16
_16
mRtmClient.getStorage().removeUserMetadata("Tony", metadata, new MetadataOptions(true, true), new ResultCallback<Void>() {
_16
@Override
_16
public void onSuccess(Void responseInfo) {
_16
log(CALLBACK, "remove user metadata success");
_16
}
_16
_16
@Override
_16
public void onFailure(ErrorInfo errorInfo) {
_16
log(ERROR, errorInfo.toString());
_16
}
_16
});

Setting the value for a metadata item that is being deleted has no effect.

The onSuccess callback notifies you of the successful completion of the storage operation. Additionally, Signaling triggers an onStorageEvent notification of event type UPDATE within 100 ms to inform all users who have subscribed to the this user's metadata.

To delete the entire set of metadata for a user, do not add any metadata items when calling removeUserMetadata. Refer to the following sample code:


_13
Metadata metadata = new Metadata();
_13
_13
mRtmClient.getStorage().removeUserMetadata("Tony", metadata, null, new ResultCallback<Void>() {
_13
@Override
_13
public void onSuccess(Void responseInfo) {
_13
log(CALLBACK, "remove user metadata success");
_13
}
_13
_13
@Override
_13
public void onFailure(ErrorInfo errorInfo) {
_13
log(ERROR, errorInfo.toString());
_13
}
_13
});

info

When terminating a user account, it is common to delete the entire set of user's metadata. Once user metadata is deleted, it cannot be recovered. If you need data restoration, back up the metadata before deleting it.

Receive storage event notifications

A storage event notification returns the StorageEvent data structure, which includes the RtmStorageEventType parameter.

To receive storage event notifications, implement an event listener. See event listeners for details. You only receive user metadata update notifications for users that you have subscribed to.

Event notification mode

Currently, Signaling only supports the full data update mode. This means that when a user's metadata is updated, the data field in the event notification contains all the metadata of the user.

Subscribe to a user's metadata

To monitor updates to a user's metadata, you subscribe to their metadata. Refer to the following sample code:


_11
mRtmClient.getStorage().subscribeUserMetadata("Tony", new ResultCallback<Void>() {
_11
@Override
_11
public void onSuccess(Void responseInfo) {
_11
log(CALLBACK, "subscribe user metadata success");
_11
}
_11
_11
@Override
_11
public void onFailure(ErrorInfo errorInfo) {
_11
log(ERROR, errorInfo.toString());
_11
}
_11
});

When there are changes in the user metadata, Signaling triggers an onStorageEvent notification of event type UPDATE within 100 ms to inform all users who have subscribed to this user's metadata.

Unsubscribe from a user's metadata

When you no longer need to receive notifications about a user's metadata updates, unsubscribe from the users's metadata. Refer to the following sample code:


_11
mRtmClient.getStorage().unsubscribeUserMetadata("Tony", new ResultCallback<Void>() {
_11
@Override
_11
public void onSuccess(Void responseInfo) {
_11
log(CALLBACK, "unsubscribe user metadata success");
_11
}
_11
_11
@Override
_11
public void onFailure(ErrorInfo errorInfo) {
_11
log(ERROR, errorInfo.toString());
_11
}
_11
});

Version control

Signaling integrates compare-and-set (CAS) version control to manage metadata updates. CAS is a concurrency control mechanism to ensure that updates to a shared resource occur only if the resource is in an expected state. The mechanism works as follows:

  1. The client reads the current version of a data item.
  2. Before making an update, the client compares the current version with the last read version number.
  3. If the versions match, the client proceeds with the update and increments the version number. If they do not match, the update is aborted.

CAS version control is useful in scenarios that require concurrency management. For instance, consider a dating application where only one user may engage in a chat session with a host. When multiple users attempt to join, only the first request is successful.

The CAS version control feature provides two independent version control parameters. Set one or more of these values according to the needs of your business scenario:

  • majorRevision parameter in the setMajorRevision method: Enable version number verification of the entire set of user metadata.

  • revision parameter of a MetadataItem: Enable version number verification of a single metadata item.

When setting user metadata, or a single user metadata item, use the revision attribute to enable or disable version control as follows:

  • To disable CAS verification, use the default value of -1 for the revision parameter.

  • To enable CAS verification, set the majorRevision or the revision parameter to a positive integer. The SDK updates the corresponding value after successfully verifying the revision number. If the specified revision number does not match the latest revision number in the database, the SDK returns an error.

The following code snippet demonstrates how to employ majorRevision and revision for updating user metadata and metadata items:


_18
Metadata metadata = new Metadata();
_18
metadata.setMajorRevision(734874892);
_18
metadata.getItems().add(new MetadataItem("Avatar", "https://your-domain/avatar/tony.png", 734874812));
_18
_18
MetadataOptions options = new MetadataOptions();
_18
options.setRecordTs(true);
_18
options.setRecordUserId(true);
_18
mRtmClient.getStorage().updateUserMetadata("Tony", metadata, options, new ResultCallback<Void>() {
_18
@Override
_18
public void onSuccess(Void responseInfo) {
_18
log(CALLBACK, "update user metadata success");
_18
}
_18
_18
@Override
_18
public void onFailure(ErrorInfo errorInfo) {
_18
log(ERROR, errorInfo.toString());
_18
}
_18
});

In this example, CAS verification for user metadata and metadata items is enabled by setting majorRevision and revision parameters to positive integers. Upon receiving the update call request, Signaling first verifies the provided major revision number against the latest value in the database. If there's a mismatch, it returns an error; if the values match, Signaling verifies the revision number for each metadata item using a similar logic.

info

When using version control, monitor onStorageEvent notifications to retrieve updated values for majorRevision and revision to ensure that the latest revision values are used for subsequent operations.

Reference

This section contains content that completes the information on this page, or points you to documentation that explains other aspects to this product.

API reference

Signaling