Skip to main content

How can I use string user IDs?

Introduction

Many apps use string usernames. To reduce development costs, Agora has added support for string user IDs. Users can now directly use their string usernames as user accounts to join the Agora channel.

To ensure smooth communication, all the users in a channel should use the same type of ID, that is, either the integer user ID, or the string user ID.

caution

This feature is in BETA. Agora recommends contacting support@agora.io before implementing this function. The following products or features do not support string user IDs:

Implementation

Before proceeding, ensure that you understand the steps and code logic for implementing the basic Video SDK functions. The Agora real-Time interaction SDK supports string user IDs across native platforms using different methods.

Native

Agora Native SDK supports using user accounts (string user ID) to identify the user:

Android/Windows:

  • registerLocalUserAccount: Registers a local user account.
  • joinChannelWithUserAccount: Joins the channel with the registered user account.

iOS/macOS:

  • registerLocalUserAccountWithAppID: Registers a local user account.
  • joinChannelByToken: Joins the channel with the registered user account.

Follow the steps to join an Agora channel with a string user account:

  1. After initializing the RtcEngine instance, call registerLocalUserAccount to register a local user account.
  2. Call the joinChannelWithUserAccount method to join a channel with the registered user account.
  3. Call the leaveChannel method to leave the channel.

API call sequence

The following diagram shows how to join a channel with a string user ID:

info

This diagram uses Java APIs as an example.

  • When calling the registerLocalUserAccount and joinChannelWithUserAccount methods, the userAccount parameter is required and cannot be empty null.

  • Agora recommends that you call registerLocalUserAccount to register an account before calling joinChannelWithUserAccount. This can reduce the time required to join a channel. You can also directly call joinChannelWithUserAccount to join the channel.

  • For other APIs, Agora still uses the Int UID parameter to identify the user. You can use getUserInfoByUid or getUserInfoByUserAccount to get the corresponding User Account or UID without having to maintain the mapping table yourself.

Sample code

Refer to the following code snippets to implement string user accounts in your project:

private void initializeAgoraEngine() {   try {    String appId = getString(R.string.agora_app_id);     mRtcEngine = RtcEngine.create(getBaseContext(), appId, mRtcEventHandler);     // Registering a user name after initialization and before joining a channel can shorten the time to join a     channelmRtcEngine.registerLocalUserAccount(appId, mLocal.userAccount);   } catch (Exception e) {     Log.e(LOG_TAG, Log.getStackTraceString(e));     throw new RuntimeException("NEED TO check rtc sdk init fatal error" + Log.getStackTraceString(e));   } } private void joinChannel() {   String token = getString(R.string.agora_access_token);   if (token.isEmpty()) {     token = null;   }   // Join a channel using the registered user   IDmRtcEngine.joinChannelWithUserAccount(token, "stringifiedChannel1", mLocal.userAccount); } 

Sample project

Agora provides an open-source String-Account demo project on Github that implements string user accounts.

API Reference

Web

Starting from v2.5.0, the uid parameter in the Client.join method can be set as either a number or a string. You can join a channel by calling the Client.join method and passing in a string uid.

Sample code

Refer to the following code sample to implement string user accounts in your project:


_2
// Set UID to 'agora' and join channel 'demo'
_2
client.join("<appid>", "demo", "<token>", "agora");

API Reference

Considerations

  • Do not mix parameter types within the same channel. If you use SDKs that do not support string usernames, only integer user IDs can be used in the channel. The following Agora SDKs support string user accounts:
    • The Native SDK: v2.8.0 and later.
    • The Web SDK: v2.5.0 and later.
  • If you change usernames to strings, ensure that all end users are upgraded synchronously.
  • If you use string user accounts to join a channel, ensure that the token generation script on your server is updated to the latest version, and that you use the same user account or its corresponding integer user ID to generate a token.
  • If the Native SDK and Web SDK join the same channel, ensure that the user id types are the same.
vundefined