圈组是网易云信 IM 即时通讯服务的全新能力，可用来帮助您快速构建“类Discord即时通讯社群”。本文介绍如何通过较少的代码集成 NetEase IM SDK （以下简称 NIM SDK）并调用 API，在您的应用中实现圈组消息收发。

使用前准备

• 了解圈组的基础概念和能力。

• 登录云信控制台完成以下操作。

  创建应用并获取 App Key 和 App Secret

  1. 在左侧导航栏中找到“应用”，并单击“创建”。
     
     2. 填写应用的基本信息后，单击“创建”。
     
     3. 创建应用后，可以在左侧导航栏中查看该应用，并单击 “App Key 管理”，并获取 App Key 和 App Secret。
     
  注册云信 IM 账号

  注册云信 IM 账号，获取 accid 和 token。accid 和 token 将用于登录云信服务端。

  1. 在左侧导航栏中单击指定应用名称，进入该应用的详情页面。
  2. 在“功能管理”中单击“账号管理”。
  
  3. 在测试页面，单击“新建账号”，并填写账号（即accid）、昵称（即 name）、密码（即 Token）后，单击“确定”。
  
  开通“圈组功能”

  在云信控制台选择应用，进入IM 免费版/专业版 > 功能权限开通 > 拓展配置 > 圈组即可配置。
  

实现流程

流程概览

实现圈组消息收发的流程，可分为下图所示的 5 大步骤。

下图可能因为网络问题无法正常展示。如遇到该问题，一般刷新页面即可正常展示。

圈组服务端与圈组服务器是两个不同概念，前者指云信服务端提供圈组功能的部分，后者为圈组的特殊概念，对应 Discord 的 Server, 为社群本身。

步骤 0：新建项目

此步骤以新建新项目为例，若集成到已有项目，可忽略此步骤

1. 启动 Xcode，在左上角选择File > New > Project。
2. 在出现的工作表中，选择 iOS 平台，并在 Application 下选择 App。
3. 配置新建项目，完成后，单击 Next。

   必须填写 Product Name 和 Organization Identifier。

4. 选择项目存储路径，单击 Create 创建项目。
   

步骤1: 集成 NIM SDK

本节仅介绍更为快速的 CocoaPods 集成方式。如需查看手动集成的具体说明，请参见手动集成。

集成前，请先前往SDK下载页面查看当前最新版本，并查询本地仓库中对应的版本是否为最新版本。若不是最新版本，建议先更新本地仓库，以确保可以集成最新的SDK版本。

    pod search NIMSDK_LITE   //本地仓库中查询NIMSDK_LITE信息
    pod repo update          //更新本地仓库

CocoaPods集成资源关键词详解：

关键词	所含资源
NIMSDK_LITE	IM即时通讯
NIMKit	NIMSDK_LITE + NIM_iOS_UIKit + 特定版本的第三方依赖库
NIMKit/Lite_Free	NIMSDK_LITE+NIM_iOS_UIKit+不限制版本的第三方依赖库

如只需要即时通讯功能，且不需NIM_iOS_UIKit组件，可在Podfile中写入：

    //IM即时通讯SDK
    pod 'NIMSDK_LITE' 

然后执行安装命令：

    pod install

步骤2: 初始化 NIM SDK

将 SDK 集成到客户端后，需要先完成 SDK 的初始化才能使用其他功能。

1. 在项目文件中引入头文件 NIMSDK.h。

   import <NIMSDK/NIMSDK.h>
   

2. 调用registerWithOption:方法初始化 SDK。

   - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
       ...
       //推荐在程序启动的时候初始化 NIMSDK    
       NSString *appKey        = @"your app key"; //云信分配的 appKey
       NIMSDKOption *option    = [NIMSDKOption optionWithAppKey:appKey]; 
       option.apnsCername      = @"your APNs cer name"; // APNs 推送证书名,如不需要推送功能,可不传
       option.pkCername        = @"your pushkit cer name"; //PushKit 推送证书名,如不需要推送功能,可不传
       [[NIMSDK sharedSDK] registerWithOption:option];
       ...
   }
   

以上提供了一个简化的初始化示例，更多初始化信息请参见初始化 SDK。

步骤3: 登录云信 IM 服务端

客户端用户在使用云信即时通讯功能前需要先登录云信 IM 服务器。请使用已注册的云信账号进行登录。

调用NIMLoginManager的login方法进行登录。示例代码如下：

    NSString *account = @"your account";
    NSString *token   = @"your token";
    [[[NIMSDK sharedSDK] loginManager] login:account
                                    token:token
                                completion:^(NSError *error) {}];

NIM SDK 支持自动重连机制。用户也可以注册监听来实时关注 IM 的登录状态，具体请参见登录章节。

步骤4: 登录云信圈组服务端

1. 发送方和接收方注册NIMQChatManagerDelegate的qchatOnlineStatus回调，监听圈组登录状态。

2. 接收方注册NIMQChatMessageManagerDelegate的onRecvMessages:方法监听圈组消息接收。

   示例代码如下：

   //收到消息
   - (void)onRecvMessages:(NSArray<NIMMessage *> *)messages {
       //处理展示等操作
   }
   

3. 发送方和接收方调用NIMQChatManager的login方法开始登录圈组服务端。

   示例代码如下：

   NIMQChatLoginParam *param = [[NIMQChatLoginParam alloc] init];
   [[[NIMSDK sharedSDK] qchatManager] login:param completion:^(NSError *error, NIMQChatLoginResult *result) {
       // your code
   }];
   

4. 登录开始后，NIMQChatManagerDelegate的qchatOnlineStatus触发回调，根据实际登录情况返回登录状态。如最终返回NIMQChatLoginStepSyncOK（数据同步完成），则代表登录流程完成。

   圈组登录状态及其变化流程与 IM 的相同，具体请参见本文文末的登录状态参考。

步骤5: 实现圈组消息收发

本节以介绍在不考虑用户权限控制（可通过身份组控制）的情况下，使用 SDK API 快速实现圈组消息收发的流程。

1. 发送方注册NIMQChatMessageManagerDelegate的`sendMessage:progress:方法监听圈组消息发送进度。

   示例代码如下：

   //发送进度
   -(void)sendMessage:(NIMMessage *)message progress:(float)progress
   {
   }
   

2. 发送方调用createServer:completion:方法创建圈组服务器。为了更加快速地实现消息收发，创建时可将inviteMode设置为NIMQChatServerInviteModeAutoEnter（发送邀请后，不需要被邀请方同意，被邀请方立即加入服务器）。

   创建成功后，需记录服务器的 ID（serverId），后续步骤将需要传入serverId。

   
   

   示例代码如下：

   NIMQChatCreateServerParam *param = [[NIMQChatCreateServerParam alloc] init];
   param.name = @"YourApp";
   param.inviteMode = NIMQChatServerInviteModeAutoEnter;
   id <NIMQChatServerManager> qchatServerManager = [[NIMSDK sharedSDK] qchatServerManager];
   [qchatServerManager createServer:param
                       completion:^(NSError *error, NIMQChatCreateServerResult *result) {
       // your code
   }];
   

3. 发送方调用createChannel:completion:方法，调用时传入上一步中创建的服务器的serverId，且将viewMode和type分别设置为NIMQChatChannelViewModePublic（公开频道）和NIMQChatChannelTypeMsg（消息频道），从而在服务器中创建一个消息类型的公开频道。

   创建成功后，需记录频道的 ID（channelId），后续步骤将需要传入channelId。

   
   

   示例代码如下：

   id<NIMQChatChannelManager> qchatChannelManager = [[NIMSDK sharedSDK] qchatChannelManager];
   NIMQChatCreateChannelParam * param = [[NIMQChatCreateChannelParam alloc] init];
   param.serverId = 123456;
   param.name = @"YourChannel";
   param.type = NIMQChatChannelTypeMsg;
   param.viewMode = NIMQChatChannelViewModePublic;
   [qchatChannelManager createChannel:param
       completion:^(NSError *__nullable error, NIMQChatChannel *__nullable result) {
       // your code
   }];
   

4. 发送方调用inviteServerMembers:completion:方法，邀请接收方 加入服务器。

   示例代码如下：

   NIMQChatInviteServerMembersParam *param = [[NIMQChatInviteServerMembersParam alloc] init];
   param.serverId = 123456;
   param.accids = @[@"yunxin1", @"yunxin2", @"yunxin3"];
   id <NIMQChatServerManager> qchatServerManager = [[NIMSDK sharedSDK] qchatServerManager];
   [qchatServerManager inviteServerMembers:param
                               completion:^(NSError *error) {
       // your code
   }];
   

5. 发送方调用sendMessage:toSession:completion:方法，调用时传入服务器与频道的ID，从而在频道中发送一条消息。

   示例代码如下：

   id<NIMQChatMessageManager> qchatMessageManager = [[NIMSDK sharedSDK] qchatMessageManager];
   NIMQChatMessage *message = [[NIMQChatMessage alloc] init];
   NIMSession * session = [NIMSession sessionForQChat:121212 qchatServerId:123456];
   message.text = @"文本消息的内容";
   [qchatMessageManager sendMessage:message
       toSession:session
       completion:^(NSError *__nullable error) {
       // your code
   }];
   

6. NIMQChatMessageManagerDelegate的onRecvMessages:触发回调，接收方收到消息。

后续步骤

为保障通信安全，如果您在调试环境中的使用的是云信控制台生成的测试用 IM 账号 和 token，请确保在后续的正式生产环境中，将其替换为通过 IM 服务端 API 生成的正式 IM 账号（accid）和 token。

登录状态参考

圈组的登录状态变化流程参见下图。图中，深蓝色元素代表登录状态，浅绿色元素代表手动登录。

下图仅以圈组登录状态的变化流程为例，IM 登录状态变化逻辑与圈组的一致，但不支持自动登录。

IM 和圈组的登录状态分别由NIMLoginStep和NIMQChatLoginStep枚举定义，各枚举项说明如下：

IM 登录状态	圈组登录状态	说明
NIMLoginStepLinking,	NIMQChatLoginStepLinking,	连接服务端
NIMLoginStepLinkOK,	NIMQChatLoginStepLinkOK,	连接服务端成功
NIMLoginStepLinkFailed,	NIMQChatLoginStepLinkFailed,	连接服务端失败
NIMLoginStepLoginOK,	NIMQChatLoginStepLoginOK,	登录成功
NIMLoginStepLoginingFailed,	NIMQChatLoginStepLoginFailed,	登录失败
NIMLoginStepSyncing,	NIMQChatLoginStepSyncing,	开始同步数据
NIMLoginStepSyncOK,	NIMQChatLoginStepSyncOK,	同步数据完成
NIMLoginStepLoseConnection,	NIMQChatLoginStepLoseConnection,	与服务端的长连接断开
NIMLoginStepNetChanged,	NIMQChatLoginStepNetChanged,	网络切换，并不是登录状态的一种, 您可通过这个状态按需进行 UI 展现