IM 即时通讯
Windows/macOS
产品介绍
简介
主要功能
产品优势
海外数据中心
IM平滑迁移方案
接口及业务限制
功能介绍
帐号集成与登录
基础消息功能
群组功能
聊天室功能
聊天室标签功能
圈组功能
多端登录与互踢策略
质量数据监控台
更新日志
Demo 更新日志
NIM SDK 更新日志
快速开始
实现单聊消息收发(不含 UI)
实现圈组消息收发(不含 UI)
开发指南
概要介绍
集成方式(当前版本)
集成方式(Windows旧版本)
集成方式(macOS旧版本)
初始化
登录登出
消息收发
最近会话
历史记录
用户资料托管
好友关系托管
事件订阅
系统通知
系统通知概述
内置系统通知管理
内置系统通知未读数
自定义系统通知收发
群组功能
群组概述
群组管理
群成员管理
群消息管理
超大群功能
开通聊天室功能
聊天室
圈组功能
初始化
登录圈组
圈组服务器管理
圈组服务器成员管理
游客功能
频道相关
频道管理
频道分组
频道分组黑白名单
频道未读数管理
搜索服务器和频道
身份组相关
身份组概述
身份组应用场景
服务器身份组
频道身份组
频道分组身份组
频道用户定制权限
自定义权限项
成员权限判定
身份组相关查询
圈组订阅机制
圈组消息相关
圈组消息收发
圈组消息撤回
圈组消息更新
圈组消息删除
会话消息回复(Thread)
圈组快捷评论
获取频道最后一条消息
消息正在输入
圈组消息搜索
圈组消息查询
查询@我的消息
服务器未读数
圈组系统通知
圈组系统通知概述
圈组系统通知收发
圈组系统通知更新
圈组各端接口命名差异
语音录制与播放
NOS云存储服务
文档转换
反垃圾(内容审核)
API 参考
Windows/macOS API 参考
状态码
IM 控制台指南
创建应用
注册 IM 账号
升级服务
配置应用客户端标识
参考文档
升级指引
开发示例
UI库指南
Demo源码导读
打包发布
类与常量定义说明
常见问题
FAQ
服务协议

实现圈组消息收发

更新时间: 2023/03/07 16:44:05

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

使用前准备

  • 下载 PC 版 NIM SDK(C++)

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

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

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

    1. 在左侧导航栏中单击指定应用名称,进入该应用的详情页面。
    2. 在“功能管理”中单击“账号管理”。
    账号管理
    3. 在测试页面,单击“新建账号”,并填写账号(即accid)、昵称(即 name)、密码(即 Token)后,单击“确定”。
    确定
    开通“圈组功能”在云信控制台选择应用,进入IM 免费版/专业版 > 功能权限开通 > 拓展配置 > 圈组即可配置。

实现流程

流程概览

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

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

uml diagram

步骤1: 集成 NIM SDK

本节仅以较为快速的 CMake 集成为例进行介绍(其他集成方式请参见集成方式),具体步骤如下:

  1. 使用 ADD_SUBDIRECTORY 命令将wrapper目录添加为子目录。

  2. 使用 INCLUDE_DIRECTORIES 方法将includewrapper文件夹添加为头文件搜索路径。

  3. 根据您的执行目标使用 TARGET_LINK_LIBRARIES 按需添加链接库即可。链接库如下:

    • nim_cpp_wrapper:NIM C++ 封装层库
    • nim_chatroom_cpp_wrapper:Chatroom C++ 封装层库
    • nim_wrapper_util:NIM 及 Chatroom C++ 封装层库通用的工具库
    • nim_tools_cpp_wrapper:NIM HTTP 组件 C++ 封装层库
    • nim_qchat_cpp_wrapper:NIM QChat 圈组 C++ 封装层库
  • 如果您的工程项目基于 CMake 管理,只需将 wrapper 工程作为您主项目的依赖即可,其他无需任何多余配置。如果您的工程项目未基于 CMake 管理,建议您在持续集成(Continuous Integration,CI)或者与其他同事协作时,通过自定义脚本在项目编译前始终通过 CMake 来生成并编译工程,从而得到需要的二进制文件产物。
  • 不建议将 CMake 产生的工程文件直接引用到项目中使用。因为 CMake 使用将绝对路径写入到工程的配置文件(.vcxproj)中,您在自己设备上生成的工程文件无法在其他设备中顺利编译。

步骤2:初始化 SDK

  1. 执行如下命令,将圈组 SDK 引入到您的本地项目。

    #include "nim_qchat_cpp_wrapper/nim_cpp_qchat_api.h" // 引入 QChat 库
    
  2. 调用QChat::Init方法将圈组 SDK 初始化。

    示例代码如下:

    QChatInitParam param;
    bool result = QChat::Init(param);
    if (!result) {
        // error handling
        return;
    }
    
  • QChatInitParam的成员参数如果不传则使用默认值。如果您仅需体验消息收发,使用默认值即可。
  • 更多初始化相关说明,请参见初始化

步骤3:登录 IM

调用nim::Login方法登录 IM 服务端。

示例代码如下:

void foo()
{
    nim::Client::Login(app_key, "app account", "token", [](const nim::LoginRes& res){
        if (login_res.res_code_ == nim::kNIMResSuccess){
            if (login_res.login_step_ == nim::kNIMLoginStepLogin){
                ···
            }
        } else {
            ···
        }
    }, "");
}

步骤4:登录圈组

  1. 接收方在登录圈组之前,调用RegRecvCb方法监听消息接收。

    示例代码如下:

    QChatRegRecvMsgCbParam reg_receive_message_cb_param;
    reg_receive_message_cb_param.cb = [this](const QChatRecvMsgResp& resp) {
        if (resp.res_code != NIMResCode::kNIMResSuccess) {
            // error handling
            return;
        }
        // process response
        // ...
    };
    Message::RegRecvCb(reg_receive_message_cb_param);
    
  2. 发送方和接收方调用PluginIn::QChatRequestLinkAddress方法获取圈组服务端的连接地址。

    请务必先完成上一步的 IM 服务端登录,否则将无法获取圈组服务端的连接地址。

    示例代码如下:

    // Note: log on to IM first
    // ...
    uint32_t ip_version = 2; // ip协议, 0:ipv4, 1:ipv6, 2:all
    PluginIn::QChatRequestLinkAddress(ip_version, [](int error_code, const std::list<std::string>& link_address_list) {
        if (error_code != 0) {
            // error handling
            return;
        }
        // process response
        // ...
    });
    

    您也可以通过服务端 API (qchat/requestAddr.action)直接获取圈组服务端的连接地址。通过服务端 API 获取,无需先登录 IM。

  3. 发送方和接收方调用QChat::Login方法登录圈组服务端。

    示例代码如下:

    QChatLoginParam param;
    param.appkey = "your appkey"; // 传入您的 App Key
    param.accid = "your accid";  // 传入您的云信 IM 账号
    param.auth_type = kNIMQChatLoginAuthTypeDefault;
    param.login_token = "your login token"; // 传入您的 Token 
    param.link_address = {"link1", "link2"}; // 传入获取的圈组服务端连接地址
    param.cb = [](const QChatLoginResp& resp) {
        if (resp.res_code != NIMResCode::kNIMResSuccess) {
            // error handling
            return;
        }
        // process response
        // ...
    };
    QChat::Login(param);
    

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

本节以发送方与接收方的消息交互为例,介绍在不考虑用户权限控制的情况下,使用 SDK API 快速实现圈组消息收发的流程。

  1. 发送方调用CreateServer方法创建圈组服务器。为更加快速实现消息收发,创建时可将invite_mode设置为kNIMQChatServerApplyModeNormal (发送邀请后,不需要被邀请方同意,被邀请方立即加入服务器)。

    示例代码如下:

    QChatServerCreateParam param;
    param.server_info.name = "server name";
    param.server_info.invite_mode = kNIMQChatServerApplyModeNormal;
    param.server_info.apply_mode = kNIMQChatServerApplyModeNormal;
    param.cb = [this](const QChatServerCreateResp& resp) {
        if (resp.res_code != NIMResCode::kNIMResSuccess) {
            // error handling
            return;
        }
        // process response
        // ...
    };
    Server::CreateServer(param);
    
  2. 发送方调用CreateChannel方法,调用时传入上一步中创建的圈组服务器的server_id ,且将view_modetype分别设置为公开模式(kNIMQChatChannelViewModePublic)和文本消息频道(kNIMQChatChannelTypeText),从而在圈组服务器中创建一个文本消息类型的公开频道。

    示例代码如下:

    QChatChannelCreateParam param;
    param.channel_info.server_id = 123456;
    param.channel_info.name = "channel name";
    param.channel_info.type = kNIMQChatChannelTypeText;
    param.channel_info.view_mode = kNIMQChatChannelViewModePublic;
    param.cb = [this](const QChatChannelCreateResp& resp) {
        if (resp.res_code != NIMResCode::kNIMResSuccess) {
            // error handling
            return;
        }
        // process response
        // ...
    };
    Channel::CreateChannel(param);
    
  3. 发送方调用Invite方法,邀请接收方加入服务器。

    示例代码如下:

    QChatServerInviteParam param;
    param.server_id = 123456param.invite_ids = {"accid1", "accid2"};
    param.postscript = "your postscript";
    param.cb = [this](const QChatServerInviteResp& resp) {
        if (resp.res_code != NIMResCode::kNIMResSuccess) {
            // error handling
            return;
        }
        // process response
        // ...
    };
    Server::Invite(param);
    
  4. 发送方调用Send方法,调用时传入服务器与公开频道的ID,从而在公开频道中发送一条消息。

    示例代码如下:

    QChatSendMessageParam param;
    param.message.server_id = 123456; // Specify the ID of the server.
    param.message.channel_id = 123456; // Specify the ID of the channel.
    param.message.msg_body = "message body"; // Specify the content of the message.
    param.message.resend_flag = false; // Specify whether to resend the message.
    param.message.msg_id = ""; // Only for resending the message. If not required, leave it empty, the SDK will generate it by default.
    param.message.history_enable = false; // Specify whether to enable cloud storage for the message.
    
    // text message
    param.message.msg_type = kNIMQChatMsgTypeText;
    auto attach = std::make_shared<QChatDefaultAttach>();
    attach->msg_attach = "msg attach";
    
    Message::Send(param);
    
    
  5. SDK 触发消息发送(SendMsgCallback)回调函数,接收方通过该回调接收消息(QChatMessage)。

后续步骤

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

常见问题

  • QChat::Init 返回 false
    • SDK 没有拷贝到可执行文件同级目录导致加载失败
    • 可执行文件和 SDK 架构不匹配
此文档是否对你有帮助?
有帮助
我要吐槽
  • 使用前准备
  • 实现流程
  • 流程概览
  • 步骤1: 集成 NIM SDK
  • 步骤2:初始化 SDK
  • 步骤3:登录 IM
  • 步骤4:登录圈组
  • 步骤5:实现圈组消息收发
  • 后续步骤
  • 常见问题