# 如何使用 String 型用户 ID? (/zh-CN/reference/faq/integration/string_uid) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). ## 场景描述 [#场景描述] :::warning[注意] 该功能目前正在验证阶段。如需使用,我们建议你联系声网[技术支持](https://ticket.shengwang.cn/)。 以下产品或功能不支持 String 型的用户 ID: - [云端录制](/zh-CN/realtime-media/cloud-recording) - [频道管理 RESTful API](/zh-CN/api-reference/api-ref/rtc/create-ban-rule) - [控制台 RESTful API](/zh-CN/api-reference/api-ref/console/create-project) ::: 很多 App 使用 String 类型的用户账号。为降低开发成本,声网新增支持 String 型的用户 ID,方便用户使用 App 账号直接加入频道。 为保证通信质量,频道内所有用户需使用同一数据类型的用户 ID,即频道内的所有用户名应同为 Int 型或同为 String 型。 ## 实现方法 [#实现方法] 开始前请确保你已了解实现基本的[音视频互动](/zh-CN/realtime-media/rtc/get-started/quick-start)的步骤及代码逻辑。声网实时互动 SDK 在 Native 端,Web 端和小程序端分别使用不同的方法实现支持 String 型用户 ID。 ### Native 端 [#native-端] 声网 RTC Native SDK 使用 User Account(String 型用户 ID)来标识用户在频道中的身份。 **Android/Windows**: - `registerLocalUserAccount`:注册本地用户 User Account。 - `joinChannelWithUserAccount`:使用 User Account 加入频道。 **iOS/macOS**: - `registerLocalUserAccountWithAppID`:注册本地用户 User Account。 - `joinChannelByToken`:使用 User Account 加入频道。 参考如下步骤,在你的项目中实现使用 String 型用户 ID 加入频道: 1. 完成初始化 RtcEngine 后,调用 `registerLocalUserAccount` 方法,注册本地用户的 User Account。 2. 调用 `joinChannelWithUserAccount` 方法,使用注册的 User Account 加入频道。 3. 离开频道时,调用 `leaveChannel` 方法。 **API 时序图** 下图以 C++ 为例展示使用 String 型用户 ID 加入频道的 API 调用时序: 其中: - 在调用 `registerLocalUserAccount` 和 `joinChannelWithUserAccount` 方法时,`userAccount` 参数均为必填,不可为 `null`。 - 声网建议你先调用 `registerLocalUserAccount` 注册 User Account,这样可以减少调用 `joinChannelWithUserAccount` 加入频道的时间。你也可以直接调用 `joinChannelWithUserAccount` 方法加入频道。 - 对于其他 API,声网仍使用 Int 型的 UID 参数标识用户身份。你可以使用 `getUserInfoByUid` 或 `getUserInfoByUserAccount` 获取对应的 User Account 或 UID,无需自己维护映射表。 #### 示例代码 [#示例代码] 以下展示使用 String 型用户 ID 的示例代码: ```java tab="Java" tabGroup="sample-code" private void initializeAgoraEngine() { try { String appId = getString(R.string.agora_app_id); mRtcEngine = RtcEngine.create(getBaseContext(), appId, mRtcEventHandler); // 初始化后、加入频道前先注册用户名,可以缩短加入频道的时间 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; } // 使用注册的用户 ID 加入频道 mRtcEngine.joinChannelWithUserAccount(token, "stringifiedChannel1", mLocal.userAccount); } ``` ```cpp tab="C++" tabGroup="sample-code" LRESULT COpenLiveDlg::OnJoinChannel(WPARAM wParam, LPARAM lParam) { IRtcEngine *lpRtcEngine = CAgoraObject::GetEngine(); CAgoraObject *lpAgoraObject = CAgoraObject::GetAgoraObject(); // 注册本地用户名 lpAgoraObject->RegisterLocalUserAccount(APP_ID, m_dlgEnterChannel.GetStringUid()); // 使用用户名加入频道 lpAgoraObject->JoinChannelWithUserAccount(strChannelName, m_dlgEnterChannel.GetStringUid()); } ``` ```swift tab="Swift" tabGroup="sample-code" func joinChannel() { // 加入频道前注册用户 ID let myStringId = "someStringId" agoraKit.registerLocalUserAccount(userAccount: myStringId, appId: myAppId) // 使用注册的用户 ID 加入频道 agoraKit.joinChannel(byUserAccount: myStringId, token: Token, channelId: "demoChannel1") { sid, uid, elapsed) in } } ``` ```objc tab="Objective-C" tabGroup="sample-code" -(void)joinChannel { // 加入频道前注册用户 ID NSString *userAccount = @"someStringId"; [self.agoraKit registerLocalUserAccount: userAccount appId: KeyCenter.AppId]; // 使用注册的用户 ID 加入频道 [self.agoraKit joinChannelByToken:token channelId:channelName userAccount:userAccount mediaOptions:options joinSuccess:nil]; } ``` ### Web 端 [#web-端] 从 v2.5.0 起,Web SDK 支持将 join 方法中的 uid 设为 Number 或 String 型。因此,你可以直接在调用该方法时,传入 String 型的用户 ID 即可。 #### 示例代码 [#示例代码-1] 你可以对照 API 时序图,参考下面的示例代码片段,在项目中实现使用 String 型用户 ID: ```javascript // 将 UID 设为 agora,然后加入频道 1024 client.join("", "1024", "", "agora"); ``` #### API 参考 [#api-参考] - [`IAgoraRTCClient.join`](/zh-CN/api-reference/rtc/web/interfaces/iagorartcclient#join) ### 小程序端 [#小程序端] 从 v2.5.6 起,小程序 SDK 支持将 `join` 与 `rejoin` 方法中的 `UidType` 设为 Int 型(默认值)或 String 型。在调用这 2 个方法时,传入与 `UidType` 所设的类型一致的用户 ID 即可。 **API 参考** - [`Client.join`](/zh-CN/api-reference/rtc/mini-program/classes/client#join) - [`Client.rejoin`](/zh-CN/api-reference/rtc/mini-program/classes/client#rejoin) ## 开发注意事项 [#开发注意事项] - 同一频道内,Int 型和 String 型的用户 ID 不可混用。如果你的频道内有不支持 String 型 User Account 的 SDK,则只能使用 Int 型的 User ID。目前支持 String 型 User Account 的 SDK 如下: - Native SDK:v2.8.0 及之后版本 - Web SDK:v2.5.0 及之后版本 - 小程序 SDK:v2.5.6 及之后版本 - 如果你将用户名切换至 String 型,请确保所有终端用户同步升级。 - 如果使用 String 型的用户 ID 加入频道,请确保你的服务端用户生成 Token 的脚本已升级至最新版本,并使用该用户 ID 或其对应的 Int 型 UID 来生成 Token。 - 如果频道中 Native SDK, Web SDK 或小程序 SDK 之间互通,请确保该两者使用的用户 ID 的类型一致。