Skip to main content

  • Core Products

  • Add-Ons

  • Extensions Marketplace

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:

Implement storage​

In the storage reference app, after the local user logs in to Signaling, you set their metadata in the form of key-value pairs. When the user modifies a value stored as metadata, you call the update method to save the new value. You show a list of all users currently in the channel. When the local user selects another user from the list, you retrieve and display their metadata. You subscribe to the metadata of remote users to be notified of changes.

Implement the user interface​

To show a list of users in the channel and enable the local user to update their status, you add the following elements to the user interface:

  • A TextView to display a caption
  • A Button to switch the local user status
  • A LinearLayout inside a ScrollView to display a list of users in the channel and their status

To update the UI, in /app/res/layout/activity_main.xml, replace the entire <ScrollView>...</ScrollView> block with the following:


_53
<TextView
_53
android:id="@+id/statusText"
_53
android:layout_width="wrap_content"
_53
android:layout_height="wrap_content"
_53
android:layout_alignTop="@id/userScrollView"
_53
android:layout_alignRight="@id/changeUserStatus"
_53
android:text="Set status:">
_53
</TextView>
_53
_53
<Button
_53
android:id="@+id/changeUserStatus"
_53
android:layout_width="125dp"
_53
android:layout_height="wrap_content"
_53
android:layout_below="@id/statusText"
_53
android:layout_marginLeft="5dp"
_53
android:layout_alignParentEnd="true"
_53
android:onClick="changeMyStatus"
_53
android:text="Available" />
_53
_53
<ScrollView
_53
android:id="@+id/userScrollView"
_53
android:layout_width="wrap_content"
_53
android:layout_height="100dp"
_53
android:layout_marginTop="10dp"
_53
android:layout_toLeftOf="@id/changeUserStatus"
_53
android:layout_alignParentStart="true"
_53
android:layout_below="@id/peer_name"
_53
android:background="#eeeeee" >
_53
_53
<LinearLayout
_53
android:id="@+id/userList"
_53
android:layout_width="match_parent"
_53
android:layout_height="wrap_content"
_53
android:orientation="vertical">
_53
</LinearLayout>
_53
</ScrollView>
_53
_53
<ScrollView
_53
android:id="@+id/messagesScrollView"
_53
android:layout_width="match_parent"
_53
android:layout_height="wrap_content"
_53
android:layout_below="@id/userScrollView"
_53
android:layout_alignParentBottom="true"
_53
android:layout_marginTop="10dp"
_53
android:fillViewport="true"
_53
android:scrollbars="vertical"
_53
android:background="#ECE5DD" >
_53
_53
<TextView
_53
android:id="@+id/message_history"
_53
android:layout_width="match_parent"
_53
android:layout_height="wrap_content" />
_53
</ScrollView>

Handle the system logic​

This section describes the steps required to use the relevant libraries and declare the necessary variables.

  1. Import the required Agora and Android libraries

    To read and write metadata and manage UI elements, add the following statements after the last import statement in /app/java/com.example.<projectname>/MainActivity:


    _6
    import io.agora.rtm.RtmMetadataItem;
    _6
    import io.agora.rtm.RtmMetadataOptions;
    _6
    import java.util.ArrayList;
    _6
    import java.util.HashMap;
    _6
    import android.graphics.Color;
    _6
    import android.widget.LinearLayout;

  2. Define variables to manage user TextViews and the user availability status

    In /app/java/com.example.<projectname>/MainActivity, add the following declarations to the MainActivity class:


    _4
    // Associate the TextView for each user with their user ID
    _4
    private HashMap<String, TextView> userTextViews
    _4
    = new HashMap<String, TextView>();
    _4
    private boolean isUserBusy = false; // User status

Read and write metadata​

To implement the use of metadata, take the following steps:

  1. Set local user metadata

    After a user successfully logs in to Signalling, you clear unwanted metadata from a previous login, and add fresh metadata that you want to share with other users. To do this:

    1. Add the following method to the MainActivity class:


      _32
      void setLocalUserMetaData() {
      _32
      // Clear previous metadata
      _32
      mRtmClient.clearLocalUserMetadata(new RtmMetadataOptions(), new ResultCallback<Void>() {
      _32
      @Override
      _32
      public void onSuccess(Void unused) {
      _32
      // Create an ArrayList of RtmMetadataItems
      _32
      ArrayList<RtmMetadataItem> metadata = new ArrayList<RtmMetadataItem>();
      _32
      metadata.add(new RtmMetadataItem("email", uid + "@example.com"));
      _32
      metadata.add(new RtmMetadataItem("gender", "F"));
      _32
      metadata.add(new RtmMetadataItem("myStatus", isUserBusy ? "busy" : "available"));
      _32
      // Set metadata options
      _32
      RtmMetadataOptions options = new RtmMetadataOptions();
      _32
      // Set local user metadata
      _32
      mRtmClient.setLocalUserMetadata(metadata, options, new ResultCallback<Void>() {
      _32
      @Override
      _32
      public void onSuccess(Void unused) {
      _32
      writeToMessageHistory( "Added LocalUserMetadata");
      _32
      }
      _32
      _32
      @Override
      _32
      public void onFailure(ErrorInfo errorInfo) {
      _32
      writeToMessageHistory( "addLocalUserMetadata failed, error: " + errorInfo.toString());
      _32
      }
      _32
      });
      _32
      }
      _32
      _32
      @Override
      _32
      public void onFailure(ErrorInfo errorInfo) {
      _32
      writeToMessageHistory("Failed to clear local user metadata " + errorInfo.toString());
      _32
      }
      _32
      });
      _32
      }

    2. Call setLocalUserMetaData after login succeeds.

      In onClickLogin, add the following to the onSuccess callback of mRtmClient.login:


      _1
      setLocalUserMetaData();

  2. Update local user metadata

    When the local user taps the button to switch their status, you update the user's metadata. To do this, add the following method to the MainActivity class:


    _11
    public void changeMyStatus(View v){
    _11
    TextView tv = (TextView) v;
    _11
    isUserBusy = !isUserBusy; // Switch status
    _11
    tv.setText(isUserBusy ? "Busy" : "Available"); // Change the button caption
    _11
    ArrayList<RtmMetadataItem> metadata = new ArrayList<RtmMetadataItem>();
    _11
    // Add a RtmMetadataItem to the ArrayList
    _11
    metadata.add(new RtmMetadataItem("myStatus", isUserBusy ? "busy" : "available"));
    _11
    RtmMetadataOptions options = new RtmMetadataOptions();
    _11
    // Update metadata with the new value
    _11
    mRtmClient.updateLocalUserMetadata(metadata, options,null);
    _11
    }

  3. Handle the onUserMetadataUpdated callback

    When you receive notification of change in a user's metadata, you update the status of the user in the user list. In onCreate, replace the onUserMetadataUpdated method under new RtmClientListener() { with the following:


    _4
    @Override
    _4
    public void onUserMetadataUpdated(String userId, RtmMetadata rtmMetadata) {
    _4
    updateUserInList(userId, rtmMetadata.items.get(0).getValue().equals("busy"));
    _4
    }

  4. Show the list of users in a channel

    When the local user successfully joins a Signalling channel, you call mRtmChannel.getMembers to obtain a list of users in the channel and add each user to the user list. To do this:

    1. In the MainActivity class, add the following method:


      _18
      private void updateChannelMemberList() {
      _18
      // Retrieve a list of users in the channel
      _18
      mRtmChannel.getMembers(new ResultCallback<List<RtmChannelMember>>() {
      _18
      @Override
      _18
      public void onSuccess(List<RtmChannelMember> rtmChannelMembers) {
      _18
      for (int i = 0; i < rtmChannelMembers.size(); i++) {
      _18
      RtmChannelMember member = rtmChannelMembers.get(i);
      _18
      // Add the user to the user list
      _18
      updateUserInList(member.getUserId(), false);
      _18
      }
      _18
      }
      _18
      _18
      @Override
      _18
      public void onFailure(ErrorInfo errorInfo) {
      _18
      _18
      }
      _18
      });
      _18
      }

    2. Call updateChannelMemberList after the user successfully joins a channel

      In onClickJoin, add the following to the onSuccess callback of mRtmChannel.join:


      _1
      updateChannelMemberList();

  5. Display a user in the list

    To fill the channel user list, you create a TextView for each user. At this time, you subscribe to the user's metadata to receive notification of changes. To add or update an item in the user list:

    1. Add the following method to the MainActivity class:


      _32
      void updateUserInList(String userID, boolean busy) {
      _32
      TextView userTextView;
      _32
      if (userTextViews.containsKey(userID)) {
      _32
      // User already in the list, update the TextView
      _32
      userTextView = userTextViews.get(userID);
      _32
      } else {
      _32
      // Create a new TextView
      _32
      userTextView = new TextView(getBaseContext());
      _32
      }
      _32
      _32
      int iconUnicode = busy ? 0x1F6AB : 0x2705;
      _32
      userTextView.setText(new String(Character.toChars(iconUnicode)) + " " + userID);
      _32
      _32
      if (!userTextViews.containsKey(userID)) { // Add a new user to the list
      _32
      // Subscribe to metadata change event for the user
      _32
      mRtmClient.subscribeUserMetadata(userID, null);
      _32
      // Set up the user's TextView
      _32
      userTextView.setTag(userID);
      _32
      userTextView.setPadding(10, 5, 5, 5);
      _32
      userTextView.setOnClickListener(onUserClick);
      _32
      userTextView.setBackgroundColor(Color.parseColor("#ADD8E6"));
      _32
      // Add the TextView to the LinearLayout
      _32
      runOnUiThread(() -> {
      _32
      LinearLayout userList = findViewById(R.id.userList);
      _32
      LinearLayout.LayoutParams params = new LinearLayout.LayoutParams(
      _32
      LinearLayout.LayoutParams.MATCH_PARENT, LinearLayout.LayoutParams.WRAP_CONTENT);
      _32
      params.setMargins(5, 5, 5, 5);
      _32
      userTextViews.put(userID, userTextView); // Store a TextView reference for future updates
      _32
      userList.addView(userTextView, params);
      _32
      });
      _32
      }
      _32
      }

    2. Add the following to the onMemberJoined callback in onClickJoin:


      _1
      updateUserInList(member.getUserId(), false);

  6. Remove a user from the list

    When a remote user leaves the channel, you remove the corresponding TextView from the user list. To do this:

    1. Add the following method to the MainActivity class:


      _13
      void removeUserFromList(String userID) {
      _13
      TextView userTextView;
      _13
      if (userTextViews.containsKey(userID)) {
      _13
      // Retrieve the corresponding TextView
      _13
      userTextView = userTextViews.get(userID);
      _13
      LinearLayout userList = findViewById(R.id.userList);
      _13
      // Remove TextView
      _13
      runOnUiThread(() -> {
      _13
      userList.removeView(userTextView);
      _13
      });
      _13
      userTextViews.remove(userID);
      _13
      }
      _13
      }

    2. Add the following to the onMemberLeft callback in onClickJoin:


      _1
      removeUserFromList(member.getUserId());

  7. Retrieve and show metadata for a selected user

    When the local user selects a user from the list, you retrieve metadata for that user and display the key-value pairs in a Toast message. To do this, add the following method to the MainActivity class:


    _27
    View.OnClickListener onUserClick = new View.OnClickListener() {
    _27
    @Override
    _27
    public void onClick(View v) {
    _27
    String userId = v.getTag().toString();
    _27
    // Retrieve metadata for the selected user
    _27
    mRtmClient.getUserMetadata(userId, new ResultCallback<RtmMetadata>(){
    _27
    @Override
    _27
    public void onSuccess(RtmMetadata userMetadata){
    _27
    // Concatenate keys and values in metadata items
    _27
    StringBuilder sb = new StringBuilder("user: " +userId);
    _27
    for (int j=0; j < userMetadata.items.size(); j++) {
    _27
    RtmMetadataItem mdItem = userMetadata.items.get(j);
    _27
    sb.append(", ").append(mdItem.getKey()).append(": ").append(mdItem.getValue());
    _27
    }
    _27
    runOnUiThread(() -> {
    _27
    Toast toast = Toast.makeText(getApplicationContext(), sb.toString(), Toast.LENGTH_LONG);
    _27
    toast.show();
    _27
    });
    _27
    }
    _27
    _27
    @Override
    _27
    public void onFailure(ErrorInfo errorInfo) {
    _27
    _27
    }
    _27
    });
    _27
    }
    _27
    };

  8. Clear the user list when the local user leaves the channel

    When the local user leaves the channel, you clear the user list. To do this, in onClickLeave, add the following lines to the onSuccess callback of mRtmChannel.leave:


    _3
    LinearLayout userList = findViewById(R.id.userList);
    _3
    runOnUiThread(userList::removeAllViews);
    _3
    userTextViews.clear();

  9. Clear metadata on logout

    When the local user logs out of Signalling, you clear the local user metadata. To do this, in onClickLogout, add the following lines to the onSuccess callback of mRtmClient.logout:


    _1
    mRtmClient.clearLocalUserMetadata(new RtmMetadataOptions(),null);

Test storage​

This section explains how to run the storage reference app and test channel and user metadata features. To run the project, take the following steps:

To test this functionality:

  1. Set the APP ID

    In agora-manager/res/raw/config.json, set appId to the AppID of your project.

  2. Set the authentication method

    Choose one of the following authentication methods:

    • Temporary token:
      1. Set rtcToken with the value of your temporary token.
      2. Set channelName - with the name of a channel you used to create the token.
    • Authentication server:
      1. Setup an Authentication server
      2. In config.json, set:
        • channelName with the name of a channel you want to join.
        • rtcToken to an empty string.
        • serverUrl to the base URL of your authentication server. For example, https://agora-token-service-production-1234.up.railway.app.

  3. Start the Android reference app

    1. In Android Studio, connect a physical Android device to your development machine.

    2. Click Run to start the app.

      A moment later you see the project installed on your device. If this is the first time you run the project, you need to grant microphone and camera access to your app.

  1. In Android Studio, open app/java/com.example.<projectname>/MainActivity, and update appId, channelName and token with the values for your temporary token.

  2. Connect a physical Android device to your development device.

  3. In Android Studio, click Run app. A moment later you see the project installed on your device.

    If this is the first time you run the project, grant microphone and camera access to your app.

  1. Click Join to start a call.

You see your app starts the proxy service and magically connects to the Agora SD-RTN™ which was not possible in a restricted network environment.

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.

Metadata API​

Use the following metadata API to implement your Signalling solution:

User metadata​

Creates an RtmMetadataItem instance.

Method


_1
public class RtmMetadataItem

Basic Use


_1
RtmMetadataItem item1 = new RtmMetadataItem("mode", "emo");

Response

Returns a RtmMetadataItem instance. RtmMetadataItem is a basic unit item of a UserMetadata and ChannelMetadata. It contains the following properties:

Property NameTypeDescription
void setKey(String key)functionSet key for current RtmMetadataItem
String getKey()functionGet key for current RtmMetadataItem
void setValue(String value)functionSet value for current RtmMetadataItem
String getValue()functionGet value for current RtmMetadataItem
void setRevision(long revision)functionSet revision for current RtmMetadataItem
long getRevision()functionGet revision for current RtmMetadataItem
long getLastUpdateTs()functionGet updated time for current RtmMetadataItem
String getAuthorUserId()functionGet the uid of who update this record for current RtmMetadataItem
Get user metadata​

Gets all metadataItems of a specified user.

Method


_1
void getUserMetadata(String userId, ResultCallback<RtmMetadata> resultCallback)

ParameterTypeRequiredDefaultDescription
userIdStringyesUnique user identifier.
resultCallbackfunctionyescallback function

Basic Use


_10
mRtmClient.getUserMetadata("Tony", new ResultCallback<RtmMetadata>(){
_10
@Override
_10
public void onSuccess(RtmMetadata userMetadata){
_10
// process success result!
_10
}
_10
@Override
_10
public void onFailure(int errorInfo){
_10
// process failure result!
_10
}
_10
});

Response

Returns a type RtmMetadata for the specific uid which contains the following properties:

Property NameTypeDescription
itemsList<RtmMetadataItem>RtmMetadataItem type array which contains a single Key-Value metadata item for user, see RtmMetadataItem for more information
majorRevisionnumberThe major revision for this user metadata
Set user metadata​

Set the local user’s metadata.

Method


_1
void setLocalUserMetadata(List<RtmMetadataItem> items, RtmMetadataOptions options, ResultCallback<Void> resultCallback)

Property NameTypeDescription
itemsList<RtmMetadataItem>RtmMetadataItem type list which contains a single Key-Value metadata item for user， see RtmMetadataItem for more information
optionsRtmMetadataOptionsadd optional propeties for current user metadata, see RtmMetadataOptions for more information
resultCallbackfunctioncallback function

RtmMetadataOptions is a set of optional properties for operations, it contains the following properties:

Property NameTypeDescription
majorRevisionnumberRevison control parametes. when the majorRevision you supplied is as same as the one in the storage, this operation will success.
enableRecordTsboolWhen it is set to true, the final RtmMetadataItem will record the updating time automatically
enableRecordUserIdboolWhen it is set to true, the final RtmMetadataItem will record who have updated this item automatically

Basic Use


_17
RtmMetadataItem item1 = new RtmMetadataItem("mode", "emo");
_17
RtmMetadataItem item2 = new RtmMetadataItem("gender", "male");
_17
ArrayList<RtmMetadataItem> metadata = new ArrayList<RtmMetadataItem>();
_17
metadata.add(item1);
_17
metadata.add(item2);
_17
RtmMetadataOptions options = new RtmMetadataOptions(-1, ture, false);
_17
mRtmClient.setLocalUserMetadata(metadata, options, new ResultCallback<Void>() {
_17
@Override
_17
public void onSuccess(Void unused) {
_17
visualLog_CALLBACK( "setLocalUserMetadata onSuccess");
_17
}
_17
_17
@Override
_17
public void onFailure(ErrorInfo errorInfo) {
_17
visualLog_CALLBACK( "setLocalUserMetadata onFailure, error: " + errorInfo.toString());
_17
}
_17
});

Response

None

caution: This operation will reset all current meatadata and set a new one.

Add user metadata​

Adds metadata items to local user’s metadata.

Method


_1
void addLocalUserMetadata(List<RtmMetadataItem> items, RtmMetadataOptions options, ResultCallback<Void> resultCallback);

Property NameTypeDescription
itemsList< RtmMetadataItem >RtmMetadataItem type array which contains a single Key-Value metadata item for user， see RtmMetadataItem for more information
optionsRtmMetadataOptionsadd optional propeties for current user metadata, see RtmMetadataOptions for more information
resultCallbackfunctioncallback function

Basic Use


_17
RtmMetadataItem item1 = new RtmMetadataItem("mode", "emo");
_17
RtmMetadataItem item2 = new RtmMetadataItem("gender", "male");
_17
ArrayList<RtmMetadataItem> metadata = new ArrayList<RtmMetadataItem>();
_17
metadata.add(item1);
_17
metadata.add(item2);
_17
RtmMetadataOptions options = new RtmMetadataOptions(-1, ture, false);
_17
mRtmClient.addLocalUserMetadata(metadata, options, new ResultCallback<Void>() {
_17
@Override
_17
public void onSuccess(Void unused) {
_17
visualLog_CALLBACK( "addLocalUserMetadata onSuccess");
_17
}
_17
_17
@Override
_17
public void onFailure(ErrorInfo errorInfo) {
_17
visualLog_CALLBACK( "addLocalUserMetadata onFailure, error: " + errorInfo.toString());
_17
}
_17
});

Response

None

Caution: This operation will add new metadata items for current user. It will report errors if the key of new RtmMetadataItem has already existed in the user metadata.

Clear user metadata​

Delete all the local user’s metadata items.

Method


_1
void clearLocalUserMetadata(RtmMetadataOptions options, ResultCallback<Void> resultCallback)

Property NameTypeDescription
optionsRtmMetadataOptionsadd optional propeties for current user metadata, see RtmMetadataOptions for more information
resultCallbackfunctioncallback function

Basic Use


_12
RtmMetadataOptions options = new RtmMetadataOptions(-1, ture, false);
_12
mRtmClient.clearLocalUserMetadata(options, new ResultCallback<Void>() {
_12
@Override
_12
public void onSuccess(Void unused) {
_12
visualLog_CALLBACK( "clearLocalUserMetadata onSuccess");
_12
}
_12
_12
@Override
_12
public void onFailure(ErrorInfo errorInfo) {
_12
visualLog_CALLBACK( "clearLocalUserMetadata onFailure, error: " + errorInfo.toString());
_12
}
_12
});

Response

None

Caution: This operation will clean all user metadata.

Update user metadata​

Update the local user’s metadata items.

Method


_1
void updateLocalUserMetadata(List<RtmMetadataItem> items, RtmMetadataOptions options, ResultCallback<Void> resultCallback)

Property NameTypeDescription
itemsList<RtmMetadataItem>RtmMetadataItem type array which contains a single Key-Value metadata item for user， see RtmMetadataItem for more information
optionsRtmMetadataOptionsadd optional propeties for current user metadata, see RtmMetadataOptions for more information
resultCallbackfunctioncallback function

Basic Use


_17
RtmMetadataItem item1 = new RtmMetadataItem("mode", "emo");
_17
RtmMetadataItem item2 = new RtmMetadataItem("gender", "male");
_17
ArrayList<RtmMetadataItem> metadata = new ArrayList<RtmMetadataItem>();
_17
metadata.add(item1);
_17
metadata.add(item2);
_17
RtmMetadataOptions options = new RtmMetadataOptions(-1, ture, false);
_17
mRtmClient.updateLocalUserMetadata(metadata, options, new ResultCallback<Void>() {
_17
@Override
_17
public void onSuccess(Void unused) {
_17
visualLog_CALLBACK( "updateLocalUserMetadata onSuccess");
_17
}
_17
_17
@Override
_17
public void onFailure(ErrorInfo errorInfo) {
_17
visualLog_CALLBACK( "updateLocalUserMetadata onFailure, error: " + errorInfo.toString());
_17
}
_17
});

Response

None

Caution : This operation can only valid for updating the existing metadata items, or it will report errors.

Delete user metadata​

Delete the local user’s metadata items.

Method


_1
void deleteLocalUserMetadata(List<RtmMetadataItem> items, RtmMetadataOptions options, ResultCallback<Void> resultCallback)

Property NameTypeDescription
itemsList< RtmMetadataItem >RtmMetadataItem type array which contains a single Key-Value metadata item for user， see RtmMetadataItem for more information
optionsRtmMetadataOptionsadd optional propeties for current user metadata, see RtmMetadataOptions for more information
resultCallbackfunctioncallback function

Basic Use


_17
RtmMetadataItem item1 = new RtmMetadataItem("mode", "");
_17
RtmMetadataItem item2 = new RtmMetadataItem("gender", "");
_17
ArrayList<RtmMetadataItem> metadata = new ArrayList<RtmMetadataItem>();
_17
metadata.add(item1);
_17
metadata.add(item2);
_17
RtmMetadataOptions options = new RtmMetadataOptions(-1, ture, false);
_17
mRtmClient.deleteLocalUserMetadata(metadata, options, new ResultCallback<Void>() {
_17
@Override
_17
public void onSuccess(Void unused) {
_17
visualLog_CALLBACK( "deleteLocalUserMetadata onSuccess");
_17
}
_17
_17
@Override
_17
public void onFailure(ErrorInfo errorInfo) {
_17
visualLog_CALLBACK( "deleteLocalUserMetadata onFailure, error: " + errorInfo.toString());
_17
}
_17
});

Response

None

Caution：This operation will always excute regardless of the existing of metadata items

Subscribe user metadata​

Subscribe to user metadata update events for a specific user.

Method


_1
void subscribeUserMetadata(String userId, ResultCallback<Void> resultCallback);

ParameterTypeRequiredDefaultDescription
useridStringyesUnique user identifier.
resultCallbackfunctionyescallback function

Basic Use


_11
mRtmClient.subscribeUserMetadata("Tony", new ResultCallback<Void>() {
_11
@Override
_11
public void onSuccess(Void unused) {
_11
visualLog_CALLBACK( "subscribeUserMetadata onSuccess");
_11
}
_11
_11
@Override
_11
public void onFailure(ErrorInfo errorInfo) {
_11
visualLog_CALLBACK( "subscribeUserMetadata onFailure, error: " + errorInfo.toString());
_11
}
_11
});

Response

None

Unsubscribe user metadata​

Unsubscribe to user metadata update events for a specific user.

Method


_1
void unsubscribeUserMetadata(String userId, ResultCallback<Void> resultCallback)

ParameterTypeRequiredDefaultDescription
userIdStringyesUnique user identifier.
resultCallbackfunctionyesecallback function

Basic Use


_11
mRtmClient.unsubscribeUserMetadata("Tony", new ResultCallback<Void>() {
_11
@Override
_11
public void onSuccess(Void unused) {
_11
visualLog_CALLBACK( "unsubscribeUserMetadata onSuccess");
_11
}
_11
_11
@Override
_11
public void onFailure(ErrorInfo errorInfo) {
_11
visualLog_CALLBACK( "unsubscribeUserMetadata onFailure, error: " + errorInfo.toString());
_11
}
_11
});

Response

None

User metadata event​

it will occur when user's metadata are updated(Add/Set/Clear/Update/Delete), You need to complete this procedure yourself, and then you can handle this event when you are subscribing user's metadata.

Method


_1
void onUserMetadataUpdated(String userId, RtmMetadata data)

Basic Use


_15
class RtmClientListener implements RtmClientListener {
_15
//..
_15
@Override
_15
public void onUserMetadataUpdated(String userId, RtmMetadata data) {
_15
visualLog_CALLBACK("onUserMetadataUpdated, userId: " + userId);
_15
for (RtmMetadataItem item: data.items) {
_15
visualLog("Item key: " + item.getKey() + ", value: " + item.getValue()
_15
+ ", revision: " + item.getRevision() + ", ts: " + item.getLastUpdateTs()
_15
+ ", uid: " + item.getAuthorUserId());
_15
}
_15
}
_15
//..
_15
}
_15
_15
rtmClient = RtmClient.createInstance(context, appId, new RtmClientListener());

Response

When this event occurs, you can recieve a uid which indicating whose metadata have changed and a type RtmMetadata for the user which contains the following properties:

Property NameTypeDescription
itemsArray( RtmMetadataItem )RtmMetadataItem type array which contains a single Key-Value metadata item for user
majorRevisionnumberThe major revision for this user metadata

Caution: It should be noted that the returned data contains the full amount of data of the current user, Add/Set/Clear/Update/Delete operation all will trigger this event, and you cannot distinguish which operation caused the current event. Need more features, you can use our new version 2.1.

Channel metadata​

Set channel metadata​

set the metadata of the channel.

Method


_1
void setChannelMetadata(List<RtmMetadataItem> items, RtmMetadataOptions options, ResultCallback<Void> resultCallback)

Property NameTypeDescription
itemsList<RtmMetadataItem>RtmMetadataItem type array which contains a single Key-Value metadata item for channel， see RtmMetadataItem for more information
optionsRtmMetadataOptionsadd optional propeties for current channel metadata, see RtmMetadataOptions for more information
resultCallbackfunctioncallback function

The RtmMetadataOptions is a set of optional properties for operations, it contains the following properties:

Property NameTypeDescription
majorRevisionnumberRevison control parametes. when the majorRevision you supplied is as same as the one in the storage, this operation will success.
enableRecordTsboolWhen it is set to true, the final RtmMetadataItem will record the updating time automatically
enableRecordUserIdboolWhen it is set to true, the final RtmMetadataItem will record who have updated this item automatically

Basic Use


_17
RtmMetadataItem item1 = new RtmMetadataItem("Announcement", "Welcome to RTM");
_17
RtmMetadataItem item2 = new RtmMetadataItem("Channel_type", "Public");
_17
ArrayList<RtmMetadataItem> metadata = new ArrayList<RtmMetadataItem>();
_17
metadata.add(item1);
_17
metadata.add(item2);
_17
RtmMetadataOptions options = new RtmMetadataOptions(-1, ture, false);
_17
mRtmChannel.setChannelMetadata(metadata, options, new ResultCallback<Void>() {
_17
@Override
_17
public void onSuccess(Void unused) {
_17
visualLog_CALLBACK( "setChannelMetadata onSuccess");
_17
}
_17
_17
@Override
_17
public void onFailure(ErrorInfo errorInfo) {
_17
visualLog_CALLBACK( "setChannelMetadata onFailure, error: " + errorInfo.toString());
_17
}
_17
});

Response

None

caution: This operation will reset all current meatadata of channel and set a new one for channel.

Add channel metadata​

Add new metadata items to the channel.

Method


_1
void addChannelMetadata(List<RtmMetadataItem> items, RtmMetadataOptions options, ResultCallback<Void> resultCallback)

Property NameTypeDescription
itemsList<(RtmMetadataItem >RtmMetadataItem type array which contains a single Key-Value metadata item for channel， see RtmMetadataItem for more information
optionsRtmMetadataOptionsadd optional propeties for current channel metadata, see RtmMetadataOptions for more information
resultCallbackfunctioncallback function

Basic Use


_17
RtmMetadataItem item1 = new RtmMetadataItem("Announcement", "Welcome to RTM");
_17
RtmMetadataItem item2 = new RtmMetadataItem("Channel_type", "Public");
_17
ArrayList<RtmMetadataItem> metadata = new ArrayList<RtmMetadataItem>();
_17
metadata.add(item1);
_17
metadata.add(item2);
_17
RtmMetadataOptions options = new RtmMetadataOptions(-1, ture, false);
_17
mRtmChannel.addChannelMetadata(metadata, options, new ResultCallback<Void>() {
_17
@Override
_17
public void onSuccess(Void unused) {
_17
visualLog_CALLBACK( "addChannelMetadata onSuccess");
_17
}
_17
_17
@Override
_17
public void onFailure(ErrorInfo errorInfo) {
_17
visualLog_CALLBACK( "addChannelMetadata onFailure, error: " + errorInfo.toString());
_17
}
_17
});

Response

None

Caution: This operation will add new metadata items for current channel. It will report errors if the key of new RtmMetadataItem has already existed in the channel metadata.

Clear channel metadata​

delete all metadata items of the channel.

Method


_1
clearChannelMetadata(RtmMetadataOptions options, ResultCallback<Void> resultCallback)

Property NameTypeDescription
optionsRtmMetadataOptionsadd optional propeties for current channel metadata, see RtmMetadataOptions for more information
resultCallbackfunctioncallback function

Basic Use


_12
RtmMetadataOptions options = new RtmMetadataOptions(-1, ture, false);
_12
mRtmChannel.clearChannelMetadata(metadata, options, new ResultCallback<Void>() {
_12
@Override
_12
public void onSuccess(Void unused) {
_12
visualLog_CALLBACK( "clearChannelMetadata onSuccess");
_12
}
_12
_12
@Override
_12
public void onFailure(ErrorInfo errorInfo) {
_12
visualLog_CALLBACK( "clearChannelMetadata onFailure, error: " + errorInfo.toString());
_12
}
_12
});

Response

None

Caution: This operation will clean all metadata of the specific channel.

Update channel metadata​

Update metadata items of the channel.

Method


_1
updateChannelMetadata(List<RtmMetadataItem> items, RtmMetadataOptions options, ResultCallback<Void> resultCallback)

Property NameTypeDescription
itemsList<RtmMetadataItem>RtmMetadataItem type array which contains a single Key-Value metadata item for channel， see RtmMetadataItem for more information
optionsRtmMetadataOptionsadd optional propeties for current channel metadata, see RtmMetadataOptions for more information
resultCallbackfunctioncallback function

Basic Use


_17
RtmMetadataItem item1 = new RtmMetadataItem("Announcement", "Welcome to RTM");
_17
RtmMetadataItem item2 = new RtmMetadataItem("Channel_type", "Public");
_17
ArrayList<RtmMetadataItem> metadata = new ArrayList<RtmMetadataItem>();
_17
metadata.add(item1);
_17
metadata.add(item2);
_17
RtmMetadataOptions options = new RtmMetadataOptions(-1, ture, false);
_17
mRtmChannel.updateChannelMetadata(metadata, options, new ResultCallback<Void>() {
_17
@Override
_17
public void onSuccess(Void unused) {
_17
visualLog_CALLBACK( "updateChannelMetadata onSuccess");
_17
}
_17
_17
@Override
_17
public void onFailure(ErrorInfo errorInfo) {
_17
visualLog_CALLBACK( "updateChannelMetadata onFailure, error: " + errorInfo.toString());
_17
}
_17
});

Response

None

Caution : This operation can only valid for updating the existing metadata items, or it will report errors.

Delete channel metadata​

delete metadata items of the channel.

Method


_1
void deleteChannelMetadata(List<RtmMetadataItem> items, RtmMetadataOptions options, ResultCallback<Void> resultCallback)

Property NameTypeDescription
itemsList<RtmMetadataItem>RtmMetadataItem type array which contains a single Key-Value metadata item for channel， see RtmMetadataItem for more information
optionsRtmMetadataOptionsadd optional propeties for current channel metadata, see RtmMetadataOptions for more information
resultCallbackfunctioncallback function

Basic Use


_17
RtmMetadataItem item1 = new RtmMetadataItem("Announcement", "");
_17
RtmMetadataItem item2 = new RtmMetadataItem("Channel_type", "");
_17
ArrayList<RtmMetadataItem> metadata = new ArrayList<RtmMetadataItem>();
_17
metadata.add(item1);
_17
metadata.add(item2);
_17
RtmMetadataOptions options = new RtmMetadataOptions(-1, ture, false);
_17
mRtmChannel.deleteChannelMetadata(metadata, options, new ResultCallback<Void>() {
_17
@Override
_17
public void onSuccess(Void unused) {
_17
visualLog_CALLBACK( "deleteChannelMetadata onSuccess");
_17
}
_17
_17
@Override
_17
public void onFailure(ErrorInfo errorInfo) {
_17
visualLog_CALLBACK( "deleteChannelMetadata onFailure, error: " + errorInfo.toString());
_17
}
_17
});

Response

None

Caution:This operation will always excute regardless of the existing of metadata items

Get channel metadata​

get all metadata items of the channel.

Method


_1
getChannelMetadata(ResultCallback<RtmMetadata> resultCallback)

ParameterTypeRequiredDefaultDescription
resultCallbackfunctionyescallback function

Basic Use


_10
mRtmChannel.getChannelMetadata( new ResultCallback<RtmMetadata>(){
_10
@Override
_10
public void onSuccess(RtmMetadata channelMetadata){
_10
// process success result!
_10
}
_10
@Override
_10
public void onFailure(int errorInfo){
_10
// process failure result!
_10
}
_10
});

Response

Returns a type RtmMetadata for the specific channel which contains the following properties:

Property NameTypeDescription
itemsList< RtmMetadataItem >RtmMetadataItem type array which contains a single Key-Value metadatafor channel, see [RtmMetadataIte](1) for more information
majorRevisionnumberThe major revision for this channel metadata

Caution: If the specific channel have not set any user metadata yet, this operation will return a empty .

Listen channel metadata update event​

When you join channel ,you will automatically Listen the Channel metadata Update Event

Channel metadata event​

This occurs when channel's metadata are updated, You need to complete this procedure yourself, and then you can handle this event when you are in the channel

Method


_1
void onMetadataUpdated(RtmMetadata data)

Basic Use


_14
private RtmChannelListener rtmChannelListener = new RtmChannelListener(){
_14
_14
@Override
_14
public void onMetadataUpdated(RtmMetadata data) {
_14
visualLog_CALLBACK("onMetadataUpdated");
_14
for (RtmMetadataItem item: data.items) {
_14
visualLog( "Item key: " + item.getKey() + ", value: " + item.getValue()
_14
+ ", revision: " + item.getRevision() + ", ts: " + item.getLastUpdateTs()
_14
+ ", userId: " + item.getAuthorUserId());
_14
}
_14
}
_14
};
_14
_14
RtmChannel rtmChannel = mRtmClient.createChannel(channelId.toString(), rtmChannelListener);

Response

When this event occurs, you can recieve a type RtmMetadata for the specific channel which contains the following properties:

Property NameTypeDescription
itemsList< RtmMetadataItem >RtmMetadataItem type array which contains a single Key-Value metadata itemfor channel
majorRevisionnumberThe major revision for this channel metadata

Caution: It should be noted that the returned data contains the full amount of data of the current channel, Add/Set/Clear/Update/Delete operation all will trigger this event, and you cannot distinguish which operation caused the current event. Need more features, you can use our new version 2.1.

Signaling