Skip to main content

How can I use string user names?

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

Introduction

Many apps use string usernames. To reduce development costs, Agora adds support for string user accounts. 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 user account, that is, either the integer user ID, or the string user account.

Implementation

Before proceeding, ensure that you understand the steps and code logic for implmenting the basic real-time communication functions.

Native

Starting from v2.8.0, the Agora Native SDK supports using user accounts to identify the user:

  • registerLocalUserAccount: Registers a user account.
  • joinChannelWithUserAccount/joinChannelByUserAccount: 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 the registerLocalUserAccount method 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 when you want to leave the channel.

API call sequence

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

This diagram uses Java APIs as an example.
  • The userAccount parameter in the registerLocalUserAccount and joinChannelWithUserAccount methods is mandatory. Do not set it as null.

  • The registerLocalUserAccount method is optional. To join a channel with a user account, you can choose either of the following:

    • Call the registerLocalUserAccount method to create a user account, and then the joinChannelWithUserAccount method to join the channel.
    • Call the joinChannelWithUserAccount method to join the channel.

    The difference between the two is that for the former, the time elapsed between calling the joinChannelWithUserAccount method and joining the channel is shorter than the latter.

  • For other APIs, Agora uses the integer user ID for identification. You can call the getUserInfoByUid or getUserInfoByUserAccount method to get the corresponding user ID or user account without maintaining the map.

For other APIs, Agora uses the integer user ID for identification. Agora maintains a mapping table object that contains the string user account and integer user ID. You can get the user ID by passing in the user account, and vice versa.

Sample code

You can also refer to the following code snippets and implement string user accounts in your peoject:


_22
// Java
_22
private void initializeAgoraEngine() {
_22
try {
_22
String appId = getString(R.string.agora_app_id);
_22
mRtcEngine = RtcEngine.create(getBaseContext(), appId, mRtcEventHandler);
_22
// Registers the local user account after initializing the Agora engine and before joining the channel.
_22
mRtcEngine.registerLocalUserAccount(appId, mLocal.userAccount);
_22
} catch (Exception e) {
_22
Log.e(LOG_TAG, Log.getStackTraceString(e));
_22
_22
throw new RuntimeException("NEED TO check rtc sdk init fatal error\n" + Log.getStackTraceString(e));
_22
}
_22
}
_22
_22
private void joinChannel() {
_22
String token = getString(R.string.agora_access_token);
_22
if (token.isEmpty()) {
_22
token = null;
_22
}
_22
// Joins the channel with the registered user account.
_22
mRtcEngine.joinChannelWithUserAccount(token, "stringifiedChannel1", mLocal.userAccount);
_22
}


_10
// Swift
_10
func joinChannel() {
_10
// Registers the local user account before joining the channel.
_10
let myStringId = "someStringId"
_10
agoraKit.registerLocalUserAccount(userAccount: myStringId, appId: myAppId)
_10
// Joins the channel with the registered user account.
_10
agoraKit.joinChannel(byUserAccount: myStringId, token: Token, channelId: "demoChannel1") {
_10
sid, uid, elapsed) in
_10
}
_10
}


_12
// C++
_12
LRESULT COpenLiveDlg::OnJoinChannel(WPARAM wParam, LPARAM lParam)
_12
{
_12
IRtcEngine *lpRtcEngine = CAgoraObject::GetEngine();
_12
CAgoraObject *lpAgoraObject = CAgoraObject::GetAgoraObject();
_12
_12
// Registers the local user account before joining the channel.
_12
lpAgoraObject->RegisterLocalUserAccount(APP_ID, m_dlgEnterChannel.GetStringUid());
_12
// Joins the channel with the registered user account.
_12
lpAgoraObject->JoinChannelWithUserAccount(TOKEN, strChannelName, m_dlgEnterChannel.GetStringUid());
_12
_12
}

We provide an open-source String-Account demo project that implements string user accounts on Github. You can try the demo and view the source code.

API Reference

Web

Starting from v2.5, 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.

API call sequence

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

Sample code

You can also refer to the following code snippets and implement string user accounts in your peoject:


_16
// Javascript
_16
// Set uid as agora and join channel 1024
_16
client.join(
_16
'<token>',
_16
'1024',
_16
'agora',
_16
function (uid) {
_16
console.log('client' + uid + 'joined channel');
_16
// Create a local stream
_16
// ...
_16
},
_16
function (err) {
_16
console.error('client join failed', err);
_16
// Error handling
_16
}
_16
);

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 your app usernames into string user accounts, ensure that all app clients are upgraded to the latest version.
  • 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 identification types are the same.