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)%3Bk(Concurrency%3A%3Atask)%3Bk(task)%3Bk(DevLang-C%2B%2B)%3Bk(TargetOS-Windows)%26rd%3Dtrue) ，上层可以使用回调或co_await协程方式调用异步接口
  • 功能基于WEB SDK，开发者可参考 Web SDK

鉴权

SDK在初始化的时候，需要提供相关参数

  • appkey : 开发者在极光平台注册的 IM 应用 appkey
  • randomStr : 20-36 长度的随机字符串， 作为签名 salt 使用
  • timestamp : 当前时间戳，用于防止重放攻击，精确到毫秒
  • signature : 签名，10 分钟后失效

签名生成算法如下:

  1. signature = md5("appkey={appkey}&timestamp={timestamp}&random_str={randomStr}&key={secret}")

其中 secret 为开发者在极光平台注册的 IM 应用 masterSecret

不建议在客户端计算签名，有泄漏masterSecret的风险

  1. //签名生成示例(Qt):
  2. auto timestamp = QDateTime::currentDateTime().toMSecsSinceEpoch();
  3. auto str = QString("appkey=007a1134fb361233c566a1cc&timestamp=%1&random_str=022cd9fd995849b58b3ef0e943421ed9&key=122d61038232226fc12d0422").arg(time);
  5. auto signature = QCryptographicHash::hash(str.toUtf8()， QCryptographicHash::Md5).toHex().toStdString();

快速开始

依赖

Windows

MacOS

  • 编译器:Xcode 10 Toolchain
  • 第三方库:cpprestsdk, 安装命令 brew install cpprestsdk

简单示例

1.使用SDK包

  1. Windows:使用NuGet程序包， 在Visual Studio 中右键单击你的项目， 选择管理Nuget程序包

    选择浏览页，搜索jmessage-cpp ， 然后安装需要的版本SDK即可

  2. 手动下载相应平台的SDK

    Windows SDK包括:

    • include: 头文件
    • lib: 链接库
    • bin:动态库

    Mac SDK包括:

    • Jmcpp.framework

2.创建Client

  • Client类提供了SDK的主要功能，所以先创建一个Client对象
  • Configuration 参数配置Client， 包括SDK缓存路径， 日志级别等， 一般默认即可
    1. #include <Jmcpp/Client.h> // 包含头文件
    2. Jmcpp::Configuration cfg; // 默认配置
    3. Jmcpp::Client client(cfg); //创建Client对象

3.在登录前， SDK应该设置相应的监听回调，处理消息接收与事件

  • SDK提供监听消息接收的回调接口，消息分为实时消息(用户在线时收到的消息)与离线消息

    1. // 监听消息
    2. client.onMessageReceive([](Jmcpp::MessagePtr msg)
    3. {
    4.     auto content = msg->content;
    5.     if(std::holds_alternative<Jmcpp::TextContent>(content))
    6.     {
    7.         auto&& imageCont = std::get<Jmcpp::TextContent>(content);
    8.         std::cout
    9.             << msg->sender.username << " send to "
    10.             << msg->receiver.username << " : "
    11.             << imageCont.text
    12.             << std::endl;
    13.     }
    14.     else if(std::holds_alternative<Jmcpp::ImageContent>(content))
    15.     {
    17.     }
    18.     else
    19.     {
    20.     }
    21. });
    23. // 监听同步消息
    24. client.onMessageSync([](std::vector<Jmcpp::MessagePtr> msgs)
    25. {
    26. });

  • SDK提供监听事件的回调接口，同样事件分为实时事件与同步事件

    1. // 监听实时事件
    2. client.onEventReceive([](Jmcpp::Event ev)
    3. {
    4.     if(std::holds_alternative<Jmcpp::ForceLogoutEvent>(ev))
    5.     {
    6.         auto&& e = std::get<Jmcpp::ForceLogoutEvent>(ev);
    8.     }
    9.     else if(std::holds_alternative<Jmcpp::MessageRetractedEvent>(ev))
    10.     {
    11.         auto&& e = std::get<Jmcpp::MessageRetractedEvent>(ev);
    13.     }
    14.     else
    15.     {
    16.         //...
    17.     }
    18. });
    20. // 监听事件同步
    21. client.onEventSync([](std::vector<Jmcpp::Event> ev)
    22. {
    23.     //...
    24. });

4.登录，鉴权，发送消息

  • SDK登录注册需要开发者鉴权，其中签名开发者应该通过某个服务或其它方式得到，不建议在客户端通过masterSecret计算，这里只是演示用法

    1. Jmcpp::Authorization auth;
    2. auth.appKey = "25b693b31d2c2ad5f072ef0c";
    3. auth.randomStr = "022cd9fd995849b58b3ef0e943421ed9";
    4. auth.timestamp = "1467967210887";// 使用时应该获取当前事件戳，这里只是演示
    5. auth.signature = "D97C2DDA3E46E5E6D482E9E8EE84AF93";//使用时应该动态计算得到，这里只是演示
    7. //登录
    8. client.login("yourUsername", "yourPassword",auth).get();
    10. // 创建一条文本消息内容
    11. auto content = client.createTextContent("hello!").get();
    12. // 创建消息，包含要发送的用户或群
    13. auto msg = client.buildMessage(Jmcpp::UserId("targetUsername"), content);
    14. // 发送消息
    15. client.sendMessage(msg).get();

5.退出登录，销毁Client

  1.      client.logout();

6.错误处理

  1. try{
  2.         client.login("yourUsername", "yourPassword", getAuthorization()).get();
  3.         auto content = client.createTextContent("hello!").get();
  4.         auto msg = client.buildMessage(Jmcpp::UserId("test"), content);
  5.         client.sendMessage(msg).get();
  6.         client.logout();
  7.     }
  8.     catch(Jmcpp::ServerException& e)
  9.     {
  10.         // API 服务器调用返回的错误
  11.         std::cout << e.what() << std::endl;
  12.     }
  13.     catch(std::system_error& e)
  14.     {
  15.         // API 调用产生的其它错误
  16.         std::cout << e.what() << std::endl;
  17.     }

完整SDK使用可以参考Windows JChat

参考文档

错误码定义：IM web SDK 错误码列表

完整 API 文档：JMessage PC SDK API