IM 即时通讯
Windows/macOS
开发指南

自定义系统通知收发

更新时间: 2022/10/10 11:47:48

NIM SDK 支持自定义系统通知的收发,帮助您快速实现多样化的业务场景。

本文介绍通过网易云信 NIM SDK 实现自定义系统通知的技术原理、具体的实现流程以及典型的应用场景。

技术原理

NIM SDK 提供自定义系统通知,既可以由客户端发起,也可以由开发者服务器发起。SDK 仅透传自定义系统通知,不负责解析和存储。通知内容由第三方 APP 自由扩展。

开发者可以根据其业务逻辑自定义一些事件状态的通知,来实现各种业务场景。例如实现单聊场景中的对方“正在输入”的功能。

实现流程

uml diagram
  1. 注册监听。
C++
  • 使用接收系统通知回调模板(ReceiveSysmsgCallback)并调用 RegSysmsgCb 方法来监听系统通知接收事件。
  • 使用接收系统通知回调模板(SendCustomSysmsgCallback)并调用 RegSendCustomSysmsgCb 监听发送自定义系统通知的回调。

示例代码如下:

//监听系统通知接收事件
SystemMsg::RegSysmsgCb([](const SysMessage& msg) {
	// process msg
});

//监听发送自定义系统通知事件
SystemMsg::RegSendCustomSysmsgCb([](const SendMessageArc& arc) {
    // process arc
});
C

示例代码如下:

//监听系统通知接收事件
static void CallbackSysmsg(const char* result, const char* json_extension, const void* callback) {
    
}
nim_sysmsg_reg_sysmsg_cb("", &CallbackSysmsg, NULL);

//监听发送自定义系统通知事件
static void CallbackSendCustomSysmsg(const char* result, const void* callback) {
    
}
nim_sysmsg_reg_custom_notification_ack_cb("", &CallbackSendCustomSysmsg, NULL);
C#

使用 RegisterCallbacks 方法注册系统通知相关回调。

  1. 构造自定义系统通知。

该方法仅提供 C++ 调用。

通过调用CreateCustomNotificationMsg 方法构造自定义系统通知。

参数说明:

参数 说明
timetag 时间戳
type 系统通知类型,具体请参见NIMSysMsgType
content 系统通知内容
receiver_id 接收者 ID
client_msg_id 本地通知 ID
msg_setting 系统通知相关配置,如是否需要推送、计数,是否支持离线发送等,具体请参见SysMessageSetting

示例代码:

std::string sysmsg = SystemMsg::CreateCustomNotificationMsg("receiver_id", kNIMSysMsgTypeCustomTeamMsg, "client_msg_id", "content", SysMessageSetting());
  1. 发送自定义系统通知。
C++

通过调用SendCustomNotificationMsg 方法发送自定义系统通知。示例代码如下:

void foo()
{
	Json::Value json;
	Json::FastWriter writer;
	json["id"] = "1";

	nim::SysMessage msg;
	msg.receiver_accid_ = ;	//接收者id
	msg.sender_accid_ = ; 	//自己id
	msg.client_msg_id_ = QString::GetGUID();	//本地定义的消息id
	msg.attach_ = writer.write(json);			//通知附件内容
	msg.type_ = nim::kNIMSysMsgTypeCustomP2PMsg; //通知类型

	nim::SystemMsg::SendCustomNotificationMsg(msg.ToJsonString());
}
C

通过调用nim_sysmsg_send_custom_notification 方法发送自定义系统通知。示例代码如下:

typedef void(*nim_sysmsg_send_custom_notification)(const char *json_msg, const char *json_extension);

void foo()
{
	//json_msg:key的定义详见系统消息字段nim_sysmsg_def.h
	Json::Value json_msg;
	json_msg[kNIMSysMsgKeyToAccount] = ; //接收者id
	json_msg[kNIMSysMsgKeyFromAccount] = ; //自己id
	json_msg[kNIMSysMsgKeyLocalClientMsgId] = 本地定义的消息id; 
	json_msg[kNIMSysMsgKeyTime] = ; //时间戳
	json_msg[kNIMSysMsgKeyAttach] = ; //通知附件内容
	json_msg[kNIMSysMsgKeyType] = ; //通知类型

	nim_sysmsg_send_custom_notification func = (nim_sysmsg_send_custom_notification) GetProcAddress(hInst, "nim_sysmsg_send_custom_notification");
	func(json_msg.toStyledString().c_str(), nullptr);
}
C#

通过调用SendCustomMessage 方法发送自定义系统通知。示例代码如下:

void foo()
{
	NIM.SysMessage.NIMSysMessageContent content = new NIM.SysMessage.NIMSysMessageContent();
	content.ClientMsgId = Guid.NewGuid().ToString();
	content.ReceiverId = ""; //接收者id
	content.SenderId = ""; //自己id
	if (_sessionType == NIM.Session.NIMSessionType.kNIMSessionTypeP2P)
		content.MsgType = NIM.SysMessage.NIMSysMsgType.kNIMSysMsgTypeCustomP2PMsg; //通知类型
	else if (_sessionType == NIM.Session.NIMSessionType.kNIMSessionTypeTeam)
		content.MsgType = NIM.SysMessage.NIMSysMsgType.kNIMSysMsgTypeCustomTeamMsg;
	content.Attachment = ""; //通知附件内容
	NIM.SysMessage.SysMsgAPI.SendCustomMessage(content);
}

一秒内默认最多调用该接口 100 次。如需上调上限,请在官网首页通过微信、在线消息或电话等方式咨询商务人员。

  1. 触发回调,收到自定义系统通知。

典型应用场景

这里以实现单聊场景中的对方“正在输入”的功能为例,示例代码如下:

C++
SystemMsg::RegSysmsgCb([](const SysMessage& msg) {
	if (msg.type_ == kNIMSysMsgTypeCustomP2PMsg) {
		// 自定义点对点消息
		Json::Value value;
		Json::Reader reader;
		if (reader.parse(msg.attach_, value) && value.isObject()) {
			auto msg_type = value["msg_type"].asString();
			if (msg_type == "typing") {
				std::cout << "收到对方正在输入的通知" << std::endl;
				// process typing notification
				// ...
				return;
			}
			// ...
		}
	}
	// ...
});

void SendTypingNotification(){
	Json::Value json;
	Json::FastWriter writer;
	json["msg_type"] = "typing";

	nim::SysMessage msg;
	msg.receiver_accid_ = ;	//接收者id
	msg.sender_accid_ = ; 	//自己id
	msg.client_msg_id_ = QString::GetGUID();	//本地定义的消息id
	msg.attach_ = writer.write(json);			//通知附件内容
	msg.type_ = nim::kNIMSysMsgTypeCustomP2PMsg; //通知类型

	nim::SystemMsg::SendCustomNotificationMsg(msg.ToJsonString());
}
C
static void CallbackSysmsg(const char* result, const char* json_extension, const void* callback) {
    // 
}
nim_sysmsg_reg_sysmsg_cb("", &CallbackSysmsg, NULL);

void SendTypingEvent() {
	//json_msg:key的定义详见系统消息字段nim_sysmsg_def.h
	Json::Value json_msg;
	Json::Value attach;
	attach["msg_type"] = "typing";
	json_msg[kNIMSysMsgKeyToAccount] = ; //接收者id
	json_msg[kNIMSysMsgKeyFromAccount] = ; //自己id
	json_msg[kNIMSysMsgKeyLocalClientMsgId] = 本地定义的消息id; 
	json_msg[kNIMSysMsgKeyTime] = ; //时间戳
	json_msg[kNIMSysMsgKeyAttach] = GetJsonStringWithNoStyled(attach); //通知附件内容
	json_msg[kNIMSysMsgKeyType] = kNIMSysMsgTypeCustomP2PMsg; //通知类型

	nim_sysmsg_send_custom_notification func = (nim_sysmsg_send_custom_notification) GetProcAddress(hInst, "nim_sysmsg_send_custom_notification");
	func(json_msg.toStyledString().c_str(), nullptr);
}

API 参考

C++
API
说明
RegSysmsgCb 监听系统通知接收事件
RegSendCustomSysmsgCb 监听发送自定义系统通知的回调
CreateCustomNotificationMsg 构造自定义系统通知
SendCustomNotificationMsg 发送自定义系统通知
C
API
说明
nim_sysmsg_reg_sysmsg_cb 监听系统通知接收事件
nim_sysmsg_reg_custom_notification_ack_cb 监听发送自定义系统通知的回调
nim_sysmsg_send_custom_notification 发送自定义系统通知
C#
API
说明
RegisterCallbacks 监听系统通知事件
SendCustomMessage 发送自定义系统通知
此文档是否对你有帮助?
有帮助
去反馈
  • 技术原理
  • 实现流程
  • 典型应用场景
  • API 参考