JMessage PC SDK 开发指南
最近更新:2021-12-15
JMessage PC SDK 开发指南
概述
JMessage PC SDK , 使用 C++语言开发, 基于 Web SDK 协议,提供易用的 C++ 接口
编译器支持 VS2017(msvc141),兼容系统 Windows 7、Windows 8/8.1、Windows 10
MacOS 支持 Xcode 10, MacOS 10.13 (x86_64)
功能
- 实时消息,离线消息,单聊,群聊,聊天室等
- 消息类型支持文本,语音,图片,文件,位置,自定义消息等
- 基于cpprestsdk的 task/then 异步接口(更多关于 task) ,上层可以使用回调或 co_await 协程方式调用异步接口
- 功能基于 WEB SDK,开发者可参考 Web SDK
鉴权
SDK 在初始化的时候,需要提供相关参数
- appkey : 开发者在极光平台注册的 IM 应用 appkey
- randomStr : 20-36 长度的随机字符串, 作为签名 salt 使用
- timestamp : 当前时间戳,用于防止重放攻击,精确到毫秒
- signature : 签名,10 分钟后失效
签名生成算法如下:
signature = md5("appkey={appkey}&timestamp={timestamp}&random_str={randomStr}&key={secret}")
signature = md5("appkey={appkey}&timestamp={timestamp}&random_str={randomStr}&key={secret}")
此代码块在浮窗中显示
其中 secret 为开发者在极光平台注册的 IM 应用 masterSecret
不建议在客户端计算签名,有泄漏 masterSecret 的风险
//签名生成示例(Qt):
auto timestamp = QDateTime::currentDateTime().toMSecsSinceEpoch();
auto str = QString("appkey=007a1134fb361233c566a1cc&timestamp=%1&random_str=022cd9fd995849b58b3ef0e943421ed9&key=122d61038232226fc12d0422").arg(time);
auto signature = QCryptographicHash::hash(str.toUtf8(), QCryptographicHash::Md5).toHex().toStdString();
//签名生成示例(Qt):
auto timestamp = QDateTime::currentDateTime().toMSecsSinceEpoch();
auto str = QString("appkey=007a1134fb361233c566a1cc&timestamp=%1&random_str=022cd9fd995849b58b3ef0e943421ed9&key=122d61038232226fc12d0422").arg(time);
auto signature = QCryptographicHash::hash(str.toUtf8(), QCryptographicHash::Md5).toHex().toStdString();
此代码块在浮窗中显示
快速开始
依赖
Windows
- 编译器:VS2017(msvc141)
- 第三方库: https://github.com/Microsoft/cpprestsdk
MacOS
- 编译器:Xcode 10 Toolchain
- 第三方库:cpprestsdk, 安装命令 brew install cpprestsdk
简单示例
1.使用 SDK 包
Windows:使用 NuGet 程序包, 在 Visual Studio 中右键单击你的项目, 选择
管理Nuget程序包
选择浏览页,搜索
jmessage-cpp
, 然后安装需要的版本 SDK 即可手动下载相应平台的 SDK
Windows SDK 包括:
- include: 头文件
- lib: 链接库
- bin:动态库
Mac SDK 包括:
- Jmcpp.framework
2.创建 Client
- Client 类提供了 SDK 的主要功能,所以先创建一个 Client 对象
- Configuration 参数配置 Client, 包括 SDK 缓存路径, 日志级别等, 一般默认即可
#include <Jmcpp/Client.h> // 包含头文件
Jmcpp::Configuration cfg; // 默认配置
Jmcpp::Client client(cfg); //创建Client对象
#include <Jmcpp/Client.h> // 包含头文件
Jmcpp::Configuration cfg; // 默认配置
Jmcpp::Client client(cfg); //创建Client对象
此代码块在浮窗中显示
3.在登录前, SDK 应该设置相应的监听回调,处理消息接收与事件
- SDK 提供监听消息接收的回调接口,消息分为实时消息(用户在线时收到的消息)与离线消息
// 监听消息
client.onMessageReceive([](Jmcpp::MessagePtr msg)
{
auto content = msg->content;
if(std::holds_alternative<Jmcpp::TextContent>(content))
{
auto&& imageCont = std::get<Jmcpp::TextContent>(content);
std::cout
<< msg->sender.username << " send to "
<< msg->receiver.username << " : "
<< imageCont.text
<< std::endl;
}
else if(std::holds_alternative<Jmcpp::ImageContent>(content))
{
}
else
{
}
});
// 监听同步消息
client.onMessageSync([](std::vector<Jmcpp::MessagePtr> msgs)
{
});
// 监听消息
client.onMessageReceive([](Jmcpp::MessagePtr msg)
{
auto content = msg->content;
if(std::holds_alternative<Jmcpp::TextContent>(content))
{
auto&& imageCont = std::get<Jmcpp::TextContent>(content);
std::cout
<< msg->sender.username << " send to "
<< msg->receiver.username << " : "
<< imageCont.text
<< std::endl;
}
else if(std::holds_alternative<Jmcpp::ImageContent>(content))
{
}
else
{
}
});
// 监听同步消息
client.onMessageSync([](std::vector<Jmcpp::MessagePtr> msgs)
{
});
此代码块在浮窗中显示
- SDK 提供监听事件的回调接口,同样事件分为实时事件与同步事件
// 监听实时事件
client.onEventReceive([](Jmcpp::Event ev)
{
if(std::holds_alternative<Jmcpp::ForceLogoutEvent>(ev))
{
auto&& e = std::get<Jmcpp::ForceLogoutEvent>(ev);
}
else if(std::holds_alternative<Jmcpp::MessageRetractedEvent>(ev))
{
auto&& e = std::get<Jmcpp::MessageRetractedEvent>(ev);
}
else
{
//...
}
});
// 监听事件同步
client.onEventSync([](std::vector<Jmcpp::Event> ev)
{
//...
});
// 监听实时事件
client.onEventReceive([](Jmcpp::Event ev)
{
if(std::holds_alternative<Jmcpp::ForceLogoutEvent>(ev))
{
auto&& e = std::get<Jmcpp::ForceLogoutEvent>(ev);
}
else if(std::holds_alternative<Jmcpp::MessageRetractedEvent>(ev))
{
auto&& e = std::get<Jmcpp::MessageRetractedEvent>(ev);
}
else
{
//...
}
});
// 监听事件同步
client.onEventSync([](std::vector<Jmcpp::Event> ev)
{
//...
});
此代码块在浮窗中显示
4.登录,鉴权,发送消息
- SDK 登录注册需要开发者鉴权,其中签名开发者应该通过某个服务或其它方式得到,不建议在客户端通过 masterSecret 计算,这里只是演示用法
Jmcpp::Authorization auth;
auth.appKey = "25b693b31d2c2ad5f072ef0c";
auth.randomStr = "022cd9fd995849b58b3ef0e943421ed9";
auth.timestamp = "1467967210887";// 使用时应该获取当前事件戳,这里只是演示
auth.signature = "D97C2DDA3E46E5E6D482E9E8EE84AF93";//使用时应该动态计算得到,这里只是演示
//登录
client.login("yourUsername", "yourPassword",auth).get();
// 创建一条文本消息内容
auto content = client.createTextContent("hello!").get();
// 创建消息,包含要发送的用户或群
auto msg = client.buildMessage(Jmcpp::UserId("targetUsername"), content);
// 发送消息
client.sendMessage(msg).get();
Jmcpp::Authorization auth;
auth.appKey = "25b693b31d2c2ad5f072ef0c";
auth.randomStr = "022cd9fd995849b58b3ef0e943421ed9";
auth.timestamp = "1467967210887";// 使用时应该获取当前事件戳,这里只是演示
auth.signature = "D97C2DDA3E46E5E6D482E9E8EE84AF93";//使用时应该动态计算得到,这里只是演示
//登录
client.login("yourUsername", "yourPassword",auth).get();
// 创建一条文本消息内容
auto content = client.createTextContent("hello!").get();
// 创建消息,包含要发送的用户或群
auto msg = client.buildMessage(Jmcpp::UserId("targetUsername"), content);
// 发送消息
client.sendMessage(msg).get();
此代码块在浮窗中显示
5.退出登录,销毁 Client
client.logout();
client.logout();
此代码块在浮窗中显示
6.错误处理
try{
client.login("yourUsername", "yourPassword", getAuthorization()).get();
auto content = client.createTextContent("hello!").get();
auto msg = client.buildMessage(Jmcpp::UserId("test"), content);
client.sendMessage(msg).get();
client.logout();
}
catch(Jmcpp::ServerException& e)
{
// API 服务器调用返回的错误
std::cout << e.what() << std::endl;
}
catch(std::system_error& e)
{
// API 调用产生的其它错误
std::cout << e.what() << std::endl;
}
try{
client.login("yourUsername", "yourPassword", getAuthorization()).get();
auto content = client.createTextContent("hello!").get();
auto msg = client.buildMessage(Jmcpp::UserId("test"), content);
client.sendMessage(msg).get();
client.logout();
}
catch(Jmcpp::ServerException& e)
{
// API 服务器调用返回的错误
std::cout << e.what() << std::endl;
}
catch(std::system_error& e)
{
// API 调用产生的其它错误
std::cout << e.what() << std::endl;
}
此代码块在浮窗中显示
完整 SDK 使用可以参考Windows JChat
参考文档
错误码定义:IM web SDK 错误码列表
完整 API 文档:JMessage PC SDK API
文档内容是否对您有帮助?