IM SDK for UE4 开发指引

概述

游密即时通讯SDK（IM SDK）为玩家提供完整的游戏内互动服务，游戏开发者无需关注IM通讯复杂的内部工作流程，只需调用IM SDK提供的接口，即可快速实现世界聊天、公会聊天、组队聊天、文字、表情、语音等多项功能。

IM SDK接口调用顺序

四步集成IM SDK

第一步 注册账号

在游密官网注册游密账号。

第二步 添加游戏，获取Appkey

在控制台添加游戏，获得接入需要的Appkey、Appsecret。

第三步 下载IM SDK包体

下载地址

第四步 开发环境配置

开发环境配置

快速接入

1. 导入IM SDK

  • 将YoumeIM解压到工程目录的Plugins文件夹下, 重新生成VS工程, 在游戏的Build.cs添加 YoumeIM 依赖, 如下所示 : 
PrivateDependencyModuleNames.AddRange(new string[] { "YoumeIM" });
  • 重新编译运行。

2. 绑定回调类

成功导入SDK后，需要使用SDK功能的关卡。首先创建一个继承 YoumeIMObserver 的对象来绑定至SDK, 用于接受SDK的回调事件。

绑定回调对象

创建一个蓝图对象继承 YoumeIMObserver , 在该对象的构造和析构函数处分别进行回调对象的绑定与解绑。

  • 接口
    UFUNCTION(BlueprintCallable, Category = "YoumeIMAPI")
    static void BindObserver(TScriptInterface<IYoumeIMObserver> Observer);

    UFUNCTION(BlueprintCallable, Category = "YoumeIMAPI")
    static void UnbindObserver();

3. 初始化

需要在游戏开始前调用 UYoumeIMAPI::Start 进行SDK的初始化, 初始化的函数主要功能是初始化IM SDK引擎。初始化接口的输入参数appKey和appSecurity需要根据实际申请得到的值进行替换, packageName目前传入空字符串即可。

  • 接口
    UFUNCTION(BlueprintCallable, Category = "YoumeIMAPI")
    static void Start(const FString appKey, const FString appSecurity, const FString packageName);

  • 参数：
    appKey: 用户游戏产品区别于其它游戏产品的标识，可以在游密官网获取、查看。
    appSecurity: 用户游戏产品的密钥，可以在游密官网获取、查看。
    packageName：游戏包名。

  • 示例：
  UYoumeIMAPI::Start("YoumeAppkey"," YoumeAppSecurity", "");

4. 登录IM系统

登录界面介绍

成功初始化IM后，需要使用IM功能时，先调用IM SDK登录接口。

  • 调用示例：

      EYIMErrorcode ymErrorcode = UYoumeIMAPI::Login("123456", "123456", "");

  • 相关接口与参数：

    • 登录接口： UFUNCTION(BlueprintCallable, Category = "YoumeIMAPI") static EYIMErrorcode Login(const FString userID, const FString password, const FString token);

    • userID：由调⽤者分配，不可为空字符串，只可由字母或数字或下划线组成，用户首次登录会自动注册所用的用户ID和密码。
    • passwd：⽤户密码，不可为空字符串，由调用者分配，二次登录时需与首次登录一致，否则会报UsernamePasswordError。
    • token：用户验证token，可选，如不使用token验证传入:""。

  • 返回值：

  • 回调接口与参数：
    登录接口是异步操作，登录成功的标识是OnLogin回调的错误码是Success；调用Login同步返回值是Success才能收到OnLogin回调；特别的如果调用Login多次，收到AlreadyLogin错误码也表示登录成功。

    • 登录回调接口： UFUNCTION(BlueprintNativeEvent, BlueprintCallable, Category = "YoumeIM Login") void OnLogin(const EYIMErrorcode& errorcode, const FString& userID);

    • userID：用户ID。
    • errorcode：错误码。

5. 进入聊天频道

频道

登录成功后，如果有群组聊天需要，比如游戏里面的世界、工会、区域等，需要进入聊天频道，调用方为聊天频道设置一个唯一的频道ID，可以进入多个频道。

  • 调用示例：

      // 可在登录成功回调里面执行
  EYIMErrorcode ymErrorcode = UYoumeIMAPI::JoinChatRoom("roomID");

  • 相关接口与参数

    • 进入频道接口： UFUNCTION(BlueprintCallable, Category = "YoumeIMAPI Room") static EYIMErrorcode JoinChatRoom(const FString chatRoomID);

    • chatRoomID：请求加入的频道ID，仅支持数字、字母、下划线组成的字符串，区分大小写，长度限制为255字节。

  • 返回值：

  • 回调接口与参数：
    进入频道接口是异步操作，进入频道成功的标识是OnJoinChatRoom回调的错误码是Success；调用JoinChatRoom同步返回值是Success才能收到OnJoinChatRoom回调。

    • 进入频道回调接口： UFUNCTION(BlueprintNativeEvent, BlueprintCallable, Category = "YoumeIM Room") void OnJoinChatRoom(const EYIMErrorcode& errorcode, const FString& chatRoomID);

    • errorcode：错误码。
    • strChatRoomID：频道ID。

6. 发送文本消息

频道

在成功登录IM后，即可发送IM消息。

  • 调用示例：

      XUINT64 iRequestID=0;
  // 发送私聊文本消息
  EYIMErrorcode ymErrorcode = UYoumeIMAPI::SendTextMessage("12345", EYIMChatType::PrivateChat, "Msg content!","attachMsg", &iRequestID);

  • 相关接口与参数：

    • 发文本消息接口： UFUNCTION(BlueprintCallable, Category = "YoumeIMAPI Message") static EYIMErrorcode SendTextMessage(const FString receiverID, EYIMChatType chatType, const FString text, const FString attachParam, int64& requestID);

    • receiverID：接收者ID，私聊传入用户ID，频道聊天传入频道ID。
    • chatType：聊天类型,私聊传1，频道聊天传2；需要频道聊天得先成功进入频道后发文本消息，此频道内的成员才能接收到消息。
    • text：聊天内容。
    • attachParam：发送文本附加信息。
    • requestID：消息序列号，用于校验一条消息发送成功与否的标识。

  • 返回值：

  • 回调接口与参数：
    发送文本消息接口是异步操作，发送文本消息成功的标识是OnSendMessageStatus回调的错误码是Success；调用SendTextMessage同步返回值是Success才能收到OnSendMessageStatus回调；文本消息发送成功，接收方会收到OnRecvMessage回调，能从该回调中取得消息内容，消息发送者等信息。

    • 发送文本消息回调接口： UFUNCTION(BlueprintNativeEvent, BlueprintCallable, Category = "YoumeIM Message") void OnSendMessageStatus(const int64& requestID, const EYIMErrorcode& errorcode, const int32& sendTime, const bool isForbidRoom, const int32& reasonType, const int64& forbidEndTime, const int64& messageID);

    • requestID：消息序列号，用于校验一条消息发送成功与否的标识。
    • errorcode：错误码。
    • sendTime：消息发送时间。
    • isForbidRoom：若发送的是频道消息，显示在此频道是否被禁言，true-被禁言，false-未被禁言。
    • reasonType：若在频道被禁言，禁言原因类型，0-未知，1-发广告，2-侮辱，3-政治敏感，4-恐怖主义，5-反动，6-色情，7-其它。
    • forbidEndTime：若在频道被禁言，禁言结束时间。
    • messageID：服务器返回的消息id。
  • 拓展功能：
    发送消息时，可以将玩家头像、昵称、角色等级、vip等级等要素打包成json格式发送。

7. 发送语音消息

发送语音消息

在成功登录IM后，可以发送语音消息。

  • 按住语音按钮时，调用SendAudioMessage启动录音。
  • 松开按钮，调用StopAudioMessage接口，发送语音消息。
  • 按住过程若需要取消发送，调用CancleAudioMessage取消本次语音发送。

  • 调用示例：

      // 启动录音
  int64 iRequestID=0;
  EYIMErrorcode ymErrorcode = UYoumeIMAPI::SendAudioMessage("12345", EYIMChatType::PrivateChat, &iRequestID);

  // 结束录音并发送
  EYIMErrorcode ymErrorcode = UYoumeIMAPI::StopAudioMessage("");

  //如需取消发送则调用取消录音
  EYIMErrorcode ymErrorcode = UYoumeIMAPI::CancleAudioMessage();

  • 相关接口与参数：

    • 发送语音消息接口： UFUNCTION(BlueprintCallable, Category = "YoumeIMAPI Message") static EYIMErrorcode SendAudioMessage(const FString receiverID, EYIMChatType chatType, int64& requestID);

      若不需要文字识别的语音，使用下面接口。 UFUNCTION(BlueprintCallable, Category = "YoumeIMAPI Message") static EYIMErrorcode SendOnlyAudioMessage(const FString receiverID, EYIMChatType chatType, int64& requestID);

    • 结束录音接口： UFUNCTION(BlueprintCallable, Category = "YoumeIMAPI Message") static EYIMErrorcode StopAudioMessage(const FString extraParam);

    • 取消录音接口： UFUNCTION(BlueprintCallable, Category = "YoumeIMAPI Message") static EYIMErrorcode CancleAudioMessage();

    • receiverID：接收者ID（⽤户ID或者频道ID）。
    • chatType：消息类型，表示私聊还是频道消息。
    • requestID：消息序列号，用于校验一条消息发送成功与否的标识。
    • extraParam：发送语音消息附加信息，主要用于调用方特别需求。

  • 返回值：

  • 回调接口与参数：
    调用StopAudioMessage接口后，会收到发送语音的回调，如果录音成功会收到开始发送语音的回调OnStartSendAudioMessage，无论录音是否成功都会收到发送语音消息结果的回调OnSendAudioMessageStatus，OnStartSendAudioMessage在接收时间上比OnSendAudioMessageStatus快，常用于上屏显示。

    • 发送语音消息回调接口： UFUNCTION(BlueprintNativeEvent, BlueprintCallable, Category = "YoumeIM Message") void OnStartSendAudioMessage(const int64& requestID, const EYIMErrorcode& errorcode, const FString& text, const FString& audioPath, const int32& audioTime);

      UFUNCTION(BlueprintNativeEvent, BlueprintCallable, Category = "YoumeIM Message") void OnSendAudioMessageStatus(const int64& requestID, const EYIMErrorcode& errorcode, const FString& text, const FString& audioPath, const int32& audioTime, const int64& sendTime, const bool isForbidRoom, const int32& reasonType, const int64& forbidEndTime, const int64& messageID);

    • requestID：消息序列号，用于校验一条消息发送成功与否的标识。
    • errorcode：错误码。
    • text：语音转文字识别的文本内容，如果没有用带语音转文字的接口，该字段为空字符串。
    • audioPath：录音生成的wav文件的本地完整路径。

    • audioTime：录音时长(单位秒)。

    • sendTime：消息发送时间。
    • isForbidRoom：若发送的是频道消息，显示在此频道是否被禁言，true-被禁言，false-未被禁言。
    • reasonType：若在频道被禁言，禁言原因类型，0-未知，1-发广告，2-侮辱，3-政治敏感，4-恐怖主义，5-反动，6-色情，7-其它。
    • forbidEndTime：若在频道被禁言，禁言结束时间。
    • messageID：服务器返回的消息id。
  • 备注：
    此套接口是异步操作，发送语音消息成功的标识是收到OnStartSendAudioMessage，或者OnSendAudioMessageStatus回调的错误码是Success；调用StopAudioMessage同步返回值是Success才能收到回调；语音消息发送成功，接收方会收到OnRecvMessage回调，能从该回调中下载语音文件。

8. 接收消息

接收消息

  • 通过OnRecvMessage接口被动接收消息，需要开发者实现。

  • 调用示例：

  • 备注：
    收到此回调，可以根据消息基类的GetMessageBody()->GetMessageType()获取消息类型并进行相应处理。

9. 接收语音消息并播放

接收语音消息

  • 通过GetMessageBody()->GetMessageType()分拣出语音消息（MessageBodyType_Voice）。
  • ⽤GetMessageID()获得消息ID。
  • 点击语音气泡，调用函数DownloadFile下载语音消息。
  • 调用方调用函数StartPlayAudio播放语音消息。

  • 调用示例：

      // 下载语音
  EYIMErrorcode ymErrorcode = UYoumeIMAPI::DownloadFile(messageID, "savePath");

  // 播放语音,可在下载成功的回调里面播放语音
  EYIMErrorcode ymErrorcode = UYoumeIMAPI::StartPlayAudio("path");

  • 相关接口和参数：

    • 下载语音消息接口： UFUNCTION(BlueprintCallable, Category = "YoumeIMAPI Message") static EYIMErrorcode DownloadFile(const FString downloadURL, const FString savePath, EYIMFileType fileType);

    • 播放语音消息接口： UFUNCTION(BlueprintCallable, Category = "YoumeIMAPI") static EYIMErrorcode StartPlayAudio(const FString path);

    • messageID：消息ID。
    • savePath：语音文件保存路径。
    • path：待播放文件路径。

  • 返回值：

  • 回调接口与参数：
    下载语音接口是异步操作，下载语音成功的标识是OnDownload回调的错误码为Success，调用DownloadFile接口同步返回值是Success才能收到OnDownload回调。成功下载语音消息后即可播放语音消息。

    • 下载回调接口： UFUNCTION(BlueprintNativeEvent, BlueprintCallable, Category = "YoumeIM Download") void OnDownload(const EYIMErrorcode& errorcode, UYIMMessage* message, const FString& savePath);

    • errorcode：错误码。
    • msg：消息基类。

    • savePath：保存路径。

    • 播放完成回调接口： UFUNCTION(BlueprintNativeEvent, BlueprintCallable, Category = "YoumeIM AudioPlay") void OnPlayCompletion(const EYIMErrorcode& errorcode, const FString& path);

    • errorcode：错误码。
    • path：文件路径。

10. 登出IM系统

注销账号时，调用登出接口Logout登出IM系统。

  • 调用示例：

      EYIMErrorcode ymErrorcode = UYoumeIMAPI::Logout();

  • 相关接口：

    • 登出接口： UFUNCTION(BlueprintCallable, Category = "YoumeIMAPI") static EYIMErrorcode Logout();

  • 返回值：

  • 回调接口：
    登出是异步操作，登出成功的标识是OnLogout回调的错误码为Success，调用Logout接口同步返回值是Success才能收到OnLogout回调。

    • 登出回调接口： UFUNCTION(BlueprintNativeEvent, BlueprintCallable, Category = "YoumeIM Login") void OnLogout(const EYIMErrorcode& errorcode);

    • errorcode：错误码。

典型场景集成方案

主要分为世界频道聊天，用户私聊，直播聊天室。集成的时都需要先初始化SDK，登录IM系统。

启动应用，初始化IM SDK

应用启动的第一时间需要调用初始化接口。

  • 接口与参数：

    • Init：初始化接口
    • appKey：用户游戏产品区别于其它游戏产品的标识，可以在游密官网获取、查看。
    • appSecurity：用户游戏产品的密钥，可以在游密官网获取、查看。
    • packageName：游戏包名。
  • 返回值：

登录应用时，登录IM系统

登录界面介绍

  • 点击登录按钮时，调用IM SDK登录接口。

  • 接口与参数：

    • Login：登录接口。
    • userID：由调⽤者分配，不可为空字符串，只可由字母或数字或下划线组成，用户首次登录会自动注册所用的用户ID和密码。
    • passwd：⽤户密码，不可为空字符串，由调用者分配，二次登录时需与首次登录一致，否则会报UsernamePasswordError。
    • token：用户验证token，可选，如不使用token验证传入:""。
  • 返回值：

典型场景

世界频道聊天

频道

  • 进入应用后，调用加入频道接口，进入世界、公会、区域等需要进入的聊天频道。
  • 应用需要为各个聊天频道设置一个唯一的频道ID。
  • 成功进入频道后，发送频道消息，文本、语音消息等。

  • 接口与参数

    • JoinChatRoom：加入频道
    • chatRoomID：请求加入的频道ID，仅支持数字、字母、下划线组成的字符串，区分大小写，长度限制为255字节。
  • 返回值：

用户私聊

  • 成功登录IM系统后，可和其它登录IM的用户发私聊消息，文本、语音消息等；发文本消息接口的聊天类型参数使用 1-私聊类型。
  • 调用流程查看发送文本消息，发送语音消息。

直播聊天室

  • 用户集成直播SDK后，导入IM SDK。
  • 初始化IM SDK。
  • 登录IM 系统。
  • 进入指定的聊天频道。
  • 发送频道消息（例如：弹幕式），调用流程查看发送文本消息。

发送文本消息

频道

  • 点击发送按钮，调用发消息接口，将输入框中的内容发送出去。
  • 发送出的消息出现在聊天框右侧。
  • 表情消息可以将表情信息打包成Json格式发送。

  • 相关接口与参数：

    • SendTextMessage：发文字消息接口。
    • receiverID：接收者ID，私聊传入用户ID，频道聊天传入频道ID。
    • chatType：聊天类型,私聊传1，频道聊天传2；需要频道聊天得先成功进入频道后发文本消息，此频道内的成员才能接收到消息。
    • text：聊天内容。
    • attachParam：发送文本附加信息。
    • requestID：消息序列号，用于校验一条消息发送成功与否的标识。

  • 返回值：

  • 拓展功能：
    发送消息时，可以将玩家头像、昵称、角色等级、vip等级等要素打包成json格式发送。

发送语音消息

发送语音消息

  • 按住语音按钮时，调用SendAudioMessage。
  • 松开按钮，调用StopAudioMessage接口，发送语音消息。
  • 按住过程若需要取消发送，调用CancleAudioMessage取消发送。

  • 相关接口与参数：

    • SendAudioMessage：发送语音消息接口。
    • StopAudioMessage：结束录音接口。

    • CancleAudioMessage：取消录音接口。

    • receiverID：接收者ID（⽤户ID或者群ID）。
    • chatType：消息类型，表示私聊还是频道消息。
    • requestID：消息序列号，用于校验一条消息发送成功与否的标识。
    • extraParam：发送语音消息附加信息，主要用于调用方特别需求。

  • 返回值：

  • 代码示例与详细说明：

接收消息

接收消息

  • 通过OnRecvMessage接口被动接收消息，需要开发者实现，接收消息进行相应的展示，如果是语音消息需要下载语音，以及下载完成后的语音播放。

  • 相关接口与参数：

    • OnRecvMessage：收消息接口。
  • 代码示例与详细说明：

接收语音消息并播放

接收语音消息

  • 通过GetMessageType()分拣出语音消息（MessageBodyType.Voice）。
  • ⽤GetMessageID()获得消息ID。
  • 点击语音气泡，调用DownloadFile接口下载语音文件。
  • 调用方播放语音文件。

  • 相关接口与参数：

    • DownloadFile：下载语音文件接口。

    • StartPlayAudio：播放语音文件接口。

    • messageID：消息ID。
    • savePath：语音文件保存路径。
    • path：待播放文件路径。

  • 返回值：

  • 代码示例与详细说明：

登出IM系统

更换账号

  • 如下两种情况需要登出IM系统：
  • 注销账号时，调用Logout接口登出IM系统。
  • 退出应用时，调用Logout接口登出IM系统。

  • 相关接口：

    • Logout：登出接口。
  • 返回值：