聊天室登录 - IM 即时通讯

开发者中心

IM 即时通讯

集成开发

聊天室登录

更新时间： 2024/07/01 15:44:15

用户在聊天室收发消息前需要先创建聊天室实例并调用 SDK 的聊天室登录接口进入聊天室。登录成功后，用户才能正常在聊天室收发消息并使用其他聊天室相关功能。

本文介绍创建聊天室实例与实现聊天室登录的流程以及相关常见问题。

支持平台

Android	iOS	Windows/macOS	Web/uni-app/小程序	Harmony
✓	✓	✓	✓	✓

技术原理

聊天室的登录过程包括以下三阶段：

获取聊天室 Link 地址
登录鉴权（建立聊天室长连接）
进入聊天室

上述任一过程失败，都会触发进入聊天室失败回调。

本地端或多端同步进入聊天室成功后，会收到 onChatroomEntered 回调。如果已在云信控制台开启了聊天室用户进出消息系统下发功能，聊天室内所有其他成员会收到回调 onChatroomMemberEnter。如未开启，可参见开通和配置聊天室功能。

根据鉴权方式，登录方式分为静态 Token 登录、动态 Token 登录和通过第三方回调登录。

您可按需实现一种或多种登录方式。

登录方式	鉴权方式	描述
静态 Token 登录	静态 Token 鉴权	静态 Token 默认永久有效，且恒定不变，除非主动调用服务端接口刷新。
动态 Token 登录	动态 Token 鉴权	动态 Token 具备时效性，适用于对于用户信息安全有较高要求的业务场景。
通过第三方回调登录	通过第三方回调鉴权	用户登录聊天室时的鉴权工作由指定的第三方服务器（可以是应用服务器）进行，云信服务端不做聊天室登录鉴权。

前提条件

实现登录聊天室前，请确保：

已开通和配置聊天室功能。
已创建聊天室，目前只能通过新版服务端 API 创建聊天室。

配置聊天室登录策略

登录策略指您的应用需要采用的一种或多种聊天室登录方式。登录聊天室前，您需要在云信控制台配置应用的聊天室登录策略。如未配置相应的登录策略，后续调用登录接口时可能因无登录权限而报错（状态码：403）。

在控制台首页应用管理中选择应用，然后单击 IM 即时通讯下的功能配置按钮进入功能配置页。
在顶部选择聊天室页签，开启聊天室功能，然后单击子功能配置
在子功能配置页选择配置聊天室登录策略。

静态 token：用户登录聊天室时需传入静态 token。静态 token 默认永久有效，且恒定不变，除非主动调用新版服务端 API刷新 Token。
动态 token：用户登录聊天室时需传入动态 token。动态 token 具备时效性，适用于对于用户信息安全有较高要求的业务场景。
第三方回调：用户登录聊天室时的鉴权工作由指定的第三方服务器（可以是应用服务器）进行，云信服务端不做聊天室登录鉴权。选择第三方回调后，请至第三方回调配置进行相关设置。

实现流程

步骤1：准备 Token

根据以上配置的登录策略，您需要获取对应的 Token 以供后续鉴权。

静态 Token：默认永久有效。如有需要，可通过云信新版服务端 API 主动刷新 Token。

您可以通过以下两种方式获取静态 Token，用于静态 Token 登录的鉴权。
- 如果您只需要进行简单的体验或者快速测试，那么可以在云信控制台创建测试用的 IM 账号，并获取与该 IM 账号相应的静态 token，获取方式详见注册 IM 账号。
- 如果您在正式的生产环境，为了保障用户的信息安全，那么需要通过云信新版服务端 API 注册 IM 账号，并获取与之相对应的静态 token。获取方式详见注册云信 IM 账号。
动态 Token：具备时效性，可在生成时设置 token 的有效期。

注册云信 IM 账号，获取 IM 账号（accountId）和静态 token。基于 App Key、App Secret 和 accountId，通过约定算法在应用服务端生成动态 token。

后续客户端可通过在登录聊天室时实现 V2NIMChatroomLoginOption#tokenProvider 方法，从回调中获取聊天室动态 token。具体实现方式详见下文动态 Token 登录。
动态登录扩展数据（LoginExtension）：适用于所有登录模式。如果在第三方回调登录模式中设置动态登录扩展数据，第三方服务器可使用该值来进行鉴权。

后续客户端可通过在登录聊天室时实现 V2NIMChatroomLoginOption#loginExtensionProvider 方法，从回调中获取聊天室动态扩展数据 loginExtension。具体实现方式详见下文通过第三方回调登录。

步骤2：创建聊天室实例

调用 newInstance 方法创建聊天室实例。调用成功后，返回聊天室实例（instanceId），聊天室实例与聊天室（roomId）形成一一绑定关系。

Android/iOS/macOS/Windows

Android

javaV2NIMChatroomClient chatroomClient = V2NIMChatroomClient.newInstance();

iOS

objective-cV2NIMChatroomClient *chatroomClient = [V2NIMChatroomClient newInstance];

macOS/Windows

cppauto chatroomClient = V2NIMChatroomClient::newInstance();
if (!chatroomClient) {
    // create instance failed
    // ...
    return;
}
auto instanceId = chatroomClient->getInstanceId();
// save instanceId to cache
// ...

Web/uni-app/小程序/Harmony

需要在创建实例时传入聊天室初始化参数。

参数名称	类型	是否必填	描述
initParams	`V2NIMChatroomInitParams`	是	聊天室初始化参数，包括应用 AppKey 和自定义的设备类型。

Web/uni-app/小程序

typescriptconst chatroom = V2NIMChatroomClient.newInstance(
    {
        appkey: 'YOUR_APPKEY'
    }
)

Harmony

typescriptconst context: common.Context = getContext(this).getApplicationContext()
const chatroom = V2NIMChatroomClient.newInstance(context，
    {
        appkey: 'YOUR_APPKEY'
    }
)

步骤3：注册聊天室登录相关事件监听

聊天室实例相关回调：

onChatroomStatus：聊天室连接状态变更回调。聊天室内所有成员均会收到该回调。
onChatroomEntered：进入聊天室回调。
onChatroomKicked：被踢出聊天室回调。被踢出聊天室后，会同时触发 onChatroomExited 回调。
onChatroomExited：退出聊天室回调。退出聊天室后，不会继续重连。

退出聊天室包括以下场景：
- 账号变更后登录失败导致退出聊天室。
- 被加入聊天室黑名单导致退出聊天室。
- 由于账号被封禁导致退出聊天室。
- 由于聊天室被关闭导致退出聊天室。

Android/iOS/macOS/Windows

调用 addChatroomClientListener 方法注册聊天室实例监听器，包括聊天室连接状态变更、进出聊天室、被踢出聊天室。示例代码如下：

Android

javachatroomClient.addChatroomClientListener(new V2NIMChatroomClientListener() {
    @Override
    public void onChatroomStatus(V2NIMChatroomStatus status, V2NIMError error) {
        
    }

    @Override
    public void onChatroomEntered() {

    }

    @Override
    public void onChatroomExited(V2NIMError error) {

    }

    @Override
    public void onChatroomKicked(V2NIMChatroomKickedInfo kickedInfo) {

    }
});

iOS

objective-c@interface ClientListener : NSObject <V2NIMChatroomClientListener>
- (void)addToClient:(NSInteger)clientId;
@end

@implementation ClientListener
- (void)addToClient:(NSInteger)clientId
{
    V2NIMChatroomClient *instance = [V2NIMChatroomClient getInstance:clientId];
    [instance addChatroomClientListener:self];
}

- (void)onChatroomStatus:(V2NIMChatroomStatus)status
                   error:(nullable V2NIMError *)error
{

}
- (void)onChatroomEntered
{

}

- (void)onChatroomExited:(nullable V2NIMError *)error
{

}

- (void)onChatroomKicked:(V2NIMChatroomKickedInfo *)kickedInfo
{

}
@end

macOS/Windows

cppV2NIMChatroomClientListener listener;
listener.onChatroomStatus = [](V2NIMChatroomStatus status, nstd::optional<V2NIMError> error) {
    // handle chatroom status
};
listener.onChatroomEntered = []() {
    // handle chatroom entered
};
listener.onChatroomExited = [](nstd::optional<V2NIMError> error) {
   // handle chatroom exited
};
listener.onChatroomKicked = [](V2NIMChatroomKickedInfo kickedInfo) {
    // handle chatroom kicked
};
chatroomClient.addChatroomClientListener(listener);

如需移除聊天室实例相关监听器，可调用 removeChatroomClientListener。

Android

javachatroomClient.removeChatroomClientListener(chatroomClientListener);

iOS

objective-c@interface ClientListener : NSObject <V2NIMChatroomClientListener>
- (void)addToClient:(NSInteger)clientId;
- (void)removeFromClient:(NSInteger)clientId;
@end

@implementation ClientListener
- (void)addToClient:(NSInteger)clientId
{
    V2NIMChatroomClient *instance = [V2NIMChatroomClient getInstance:clientId];
    [instance addChatroomClientListener:self];
}

- (void)removeFromClient:(NSInteger)clientId
{
    V2NIMChatroomClient *instance = [V2NIMChatroomClient getInstance:clientId];
    [instance removeChatroomClientListener:self];
}

- (void)onChatroomStatus:(V2NIMChatroomStatus)status
                   error:(nullable V2NIMError *)error
{

}
- (void)onChatroomEntered
{

}

- (void)onChatroomExited:(nullable V2NIMError *)error
{

}

- (void)onChatroomKicked:(V2NIMChatroomKickedInfo *)kickedInfo
{

}
@end

macOS/Windows

cppV2NIMChatroomClientListener listener;
// ...
chatroomClient.addChatroomClientListener(listener);
// ...
chatroomClient.removeChatroomClientListener(listener);

Web/uni-app/小程序/Harmony

调用 on("EventName") 方法注册聊天室实例监听器，包括聊天室连接状态变更、进出聊天室、被踢出聊天室。

Web/uni-app/小程序

typescriptchatroom.on("onChatroomStatus", function (status: V2NIMChatroomStatus, err?: V2NIMError) {})
chatroom.on("onChatroomEntered", function () {})
chatroom.on("onChatroomExited", function (err?: V2NIMError) {})
chatroom.on("onChatroomKicked", function (kickedInfo: V2NIMChatroomKickedInfo) {})

Harmony

typescriptconst chatroom = this.getInstance(instanceId)
chatroom.on("onChatroomStatus",  (status: V2NIMChatroomStatus, err?: V2NIMError) => {
})
chatroom.on("onChatroomEntered",  ()=> {
})
chatroom.on("onChatroomExited", (err?: V2NIMError) => {
})
chatroom.on("onChatroomKicked", (kickedInfo: V2NIMChatroomKickedInfo)=> {
})

如需移除登录相关监听器，可调用 off("EventName")。

Web/uni-app/小程序

typescriptchatroom.off("onChatroomStatus", function (status: V2NIMChatroomStatus, err?: V2NIMError) {})
chatroom.off("onChatroomEntered", function () {})
chatroom.off("onChatroomExited", function (err?: V2NIMError) {})
chatroom.off("onChatroomKicked", function (kickedInfo: V2NIMChatroomKickedInfo) {})

Harmony

typescriptchatroom.off("onChatroomStatus", function (status: V2NIMChatroomStatus, err?: V2NIMError) {})
chatroom.off("onChatroomEntered", function () {})
chatroom.off("onChatroomExited", function (err?: V2NIMError) {})
chatroom.off("onChatroomKicked", function (kickedInfo: V2NIMChatroomKickedInfo) {})

步骤4：获取聊天室地址

Harmony 可跳过此步骤。

在登录聊天室之前，需要先提前获取聊天室地址。可以通过以下两种方式获取：

若当前客户端已登录 IM，那么可以通过 getChatroomLinkAddress 方法获取指定聊天室的地址。

Android

javaNIMClient.getService(V2NIMLoginService.class).getChatroomLinkAddress("123", new V2NIMSuccessCallback<List<String>>() {
            @Override
            public void onSuccess(List<String> result) {
                // get success
            }
        }, new V2NIMFailureCallback() {
            @Override
            public void onFailure(V2NIMError error) {
                // get failed
            }
        });

iOS

objective-cNSString *roomId = @"36";
[NIMSDK.sharedSDK.v2LoginService getChatroomLinkAddress:roomId
                                                success:^(NSArray<NSString *> *links) {
                                                    // get success
                                                }
                                                failure:^(V2NIMError *error) {
                                                    // get failed
                                                }];

macOS/Windows

cpploginService.getChatroomLinkAddress(
    "roomId",
    [](nstd::vector<nstd::string> linkAddresses) {
        // handle link addresses
    },
    [](V2NIMError error) {
        // handle error
    });

Web/uni-app/小程序

typescriptconst addressArray = await nim.V2NIMLoginService.getChatroomLinkAddress('36', isMiniApp)

若当前客户端未登录 IM，那么 SDK 无法获取聊天室服务器的地址，需要客户端向开发者应用服务器请求该地址，而应用服务器需要向网易云信服务器请求，然后将请求结果原路返回给客户端。具体请参考获取聊天室地址服务端 API。

步骤5：登录聊天室

通过调用 enter 方法建立聊天室长连接，登录聊天室，对应用户手动输入登录账号密码的场景。

调用后，SDK 会自动连接聊天室，传递用户信息并返回登录结果。登录过程中用户可主动取消登录。如果因为网络或其他原因导致服务端长时间未响应，用户未主动取消登录，SDK 将在 45 秒后自动重连，并返回错误码，详情请参见错误码。

Android

javapublic void enter(String roomId, V2NIMChatroomEnterParams enterParams, V2NIMSuccessCallback<V2NIMChatroomEnterResult> success, V2NIMFailureCallback failure)

参数名称	类型	是否必填	默认值	描述
`roomId`	String	是	-	聊天室 ID。如果为空、不合法、不存在则返回 191004 参数错误。
`enterParams`	`V2NIMChatroomEnterParams`	是	-	进入聊天室相关参数。
`success`	`V2NIMSuccessCallback`	是	-	进入聊天室成功回调，返回 `V2NIMChatroomEnterResult`。
`failure`	`V2NIMFailureCallback`	是	-	进入聊天室失败回调，返回错误码。

iOS

objective-c- (void)enter:(NSString *)roomId
  enterParams:(V2NIMChatroomEnterParams *)enterParams
      success:(nullable V2NIMChatroomEnterResultCallback)success
      failure:(nullable V2NIMFailureCallback)failure;

参数名称	类型	是否必填	默认值	描述
`roomId`	NSString *	是	-	聊天室 ID。如果为空、不合法、不存在则返回 191004 参数错误。
`enterParams`	`V2NIMChatroomEnterParams`	是	-	进入聊天室相关参数。
`success`	`V2NIMChatroomEnterResultCallback`	是	-	进入聊天室成功回调，可自定义。
`failure`	`V2NIMFailureCallback`	是	-	进入聊天室失败回调，返回错误码。

macOS/Windows

cppvirtual void enter(std::string roomId,
                   V2NIMChatroomEnterParams enterParams,
                   V2NIMSuccessCallback<V2NIMChatroomEnterResult> success,
                   V2NIMFailureCallback failure) = 0;

参数名称	类型	是否必填	默认值	描述
`roomId`	std::string	是	-	聊天室 ID。如果为空、不合法、不存在则返回 191004 参数错误。
`enterParams`	`V2NIMChatroomEnterParams`	是	-	进入聊天室相关参数。
`success`	`V2NIMSuccessCallback`	是	-	进入聊天室成功回调，返回 `V2NIMChatroomEnterResult`。
`failure`	`V2NIMFailureCallback`	是	-	进入聊天室失败回调，返回错误码。

Web/uni-app/小程序

typescriptenter(roomId: string, enterParams: V2NIMChatroomEnterParams): Promise<V2NIMChatroomEnterResult>

参数名称	类型	是否必填	默认值	描述
`roomId`	string	是	-	聊天室 ID。如果为空、不合法、不存在则返回 191004 参数错误。
`enterParams`	`V2NIMChatroomEnterParams`	是	-	进入聊天室相关参数。

Harmony

typescriptenter(roomId: string, enterParams: V2NIMChatroomEnterParams): Promise<V2NIMChatroomEnterResult>

参数名称	类型	是否必填	默认值	描述
`roomId`	string	是	-	聊天室 ID。如果为空、不合法、不存在则返回 191004 参数错误。
`enterParams`	`V2NIMChatroomEnterParams`	是	-	进入聊天室相关参数。

V2NIMChatroomEnterParams 的参数说明：

参数名称	类型	是否必填	默认值	描述
`anonymousMode`	Boolean	否	false	是否为匿名模式进入聊天室。在匿名模式下不能发消息，只能收消息。
`accountId`	String	否	null	用户账号。若为匿名模式，则可以不填，SDK 内部会生成账号。规则：nimanon_ UUID.randomUUID().toString()，建议全局缓存。如果为非匿名模式，则该参数必填，且必须为合法账号。
`token`	String	否	null	静态 token，静态 Token 鉴权（V2NIMChatroomLoginOption.authType=0）时必填，否则可以不填。
`roomNick`	String	否	账号对应信息	进入聊天室后显示的昵称。可以不填，默认显示账号对应相关信息，例如：匿名模式则默认昵称为账号名称。
`roomAvatar`	String	否	账号对应信息	进入聊天室后显示的头像，可通过 `V2NIMStorageService.uploadFile` 方法上传头像。可以不填，默认显示账号对应相关信息，例如：匿名模式则默认头像为空。
`timeout`	Integer	否	60	调用 `enter` 方法进入聊天室的超时时间。若超过该时间未成功进入聊天室，则返回失败回调。
`loginOption`	`V2NIMChatroomLoginOption`	否	null	聊天室登录配置。包括：鉴权方式 `authType`（`V2NIMLoginAuthType`），包括静态 Token 鉴权（默认）、动态 Token 鉴权、通过第三方回调鉴权。动态 Token 回调 `tokenProvider`（`V2NIMChatroomTokenProvider`），若使用动态 Token 鉴权（authType=1）则为必填。该回调在登录连接完成、登录鉴权校验前触发。若函数执行有异常或返回非预期内容（非法字符串），则登录中止并报错。用户登录业务扩展数据回调 `loginExtensionProvider`（`V2NIMChatroomLoginExtensionProvider`），若使用第三方回调鉴权（authType=2）则为必填。该回调在登录连接完成、登录鉴权校验前触发。若函数执行有异常或返回非预期内容（非法字符串），则登录中止并报错。
`linkProvider`	`V2NIMChatroomLinkProvider`	是	-	聊天室连接地址回调，SDK 通过两种方式获取：若已登录 IM 且在线，则调用 `V2NIMLoginService.getChatroomLinkAddress` 方法获取聊天室连接地址。若未登录 IM，则请求业务服务器，通过新版服务端 API 获取聊天室地址。
`serverExtension`	String	否	null	服务端扩展字段，建议使用 JSON 格式，多端同步。长度上限为 4096 字符。
`notificationExtension`	String	否	null	进入聊天室通知的扩展字段，长度上限为 2048 字符。
`tagConfig`	`V2NIMChatroomTagConfig`	否	null	进入聊天室的标签信息配置。
`locationConfig`	`V2NIMChatroomLocationConfig`	否	null	进入聊天室的空间位置信息配置。
`antispamConfig`	`V2NIMAntispamConfig`	否	null	易盾反垃圾检测。若不需要反垃圾检测，或已开启安全通，则不需要配置。若不使用安全通默认配置，需要定制审核规则，则配置该字段。