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:

Cloud Recording

RTMP Converter

Channel Management RESTful API

Console RESTful API

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:

After initializing the RtcEngine instance, call the registerLocalUserAccount method to register a loca user account.
Call the joinChannelWithUserAccount method to join a channel with the registered user account.
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:

// Java
private void initializeAgoraEngine() {
  try {
    String appId = getString(R.string.agora_app_id);
    mRtcEngine = RtcEngine.create(getBaseContext(), appId, mRtcEventHandler);
    // Registers the local user account after initializing the Agora engine and before joining the channel.
    mRtcEngine.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\n" + Log.getStackTraceString(e));
  }
}
private void joinChannel() {
  String token = getString(R.string.agora_access_token);
  if (token.isEmpty()) {
    token = null;
  }
  // Joins the channel with the registered user account.
  mRtcEngine.joinChannelWithUserAccount(token, "stringifiedChannel1", mLocal.userAccount);
}

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

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

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:

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

API Reference

Client.join

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.

Introduction​

Implementation​

Native​

Web​

Considerations​

Introduction

Implementation

Native

Web

Considerations