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 依赖, 如下所示 :

TEXT

PrivateDependencyModuleNames.AddRange(new string[] { "YoumeIM" });

重新编译运行。

2. 绑定回调类

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

绑定回调对象

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

接口

TEXT

    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目前传入空字符串即可。

接口

TEXT

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

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

C++

  UYoumeIMAPI::Start("YoumeAppkey"," YoumeAppSecurity", "");

4. 登录IM系统

登录界面介绍

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

调用示例：

C++

    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验证传入:""。
返回值：
- EYIMErrorcode：错误码，详细描述见错误码定义。
回调接口与参数：
登录接口是异步操作，登录成功的标识是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，可以进入多个频道。

调用示例：

C++

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

相关接口与参数
- 进入频道接口： UFUNCTION(BlueprintCallable, Category = "YoumeIMAPI Room") static EYIMErrorcode JoinChatRoom(const FString chatRoomID);
- chatRoomID：请求加入的频道ID，仅支持数字、字母、下划线组成的字符串，区分大小写，长度限制为255字节。
返回值：
- EYIMErrorcode：错误码，详细描述见错误码定义。
回调接口与参数：
进入频道接口是异步操作，进入频道成功的标识是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消息。

调用示例：

C++

    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：消息序列号，用于校验一条消息发送成功与否的标识。
返回值：
- EYIMErrorcode：错误码，详细描述见错误码定义。
回调接口与参数：
发送文本消息接口是异步操作，发送文本消息成功的标识是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取消本次语音发送。

调用示例：

C++

    // 启动录音
    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：发送语音消息附加信息，主要用于调用方特别需求。
返回值：
- EYIMErrorcode：错误码，详细描述见错误码定义。
回调接口与参数：
调用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 后先检查同步错误码；同步调用成功表示请求已受理，仍需等待最终结果回调。接收方通过 OnRecvMessage 获取语音消息并下载语音文件。

8. 接收消息

接收消息

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

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

9. 接收语音消息并播放

接收语音消息

通过GetMessageBody()->GetMessageType()分拣出语音消息（MessageBodyType_Voice）。

⽤GetMessageID()获得消息ID。

点击语音气泡，调用函数DownloadFile下载语音消息。

调用方调用函数StartPlayAudio播放语音消息。

调用示例：

C++

    // 下载语音
    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：待播放文件路径。
返回值：
- EYIMErrorcode：错误码，详细描述见错误码定义。
回调接口与参数：
下载语音接口是异步操作，下载语音成功的标识是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系统。

调用示例：

C++

    EYIMErrorcode ymErrorcode = UYoumeIMAPI::Logout();

相关接口：
- 登出接口： UFUNCTION(BlueprintCallable, Category = "YoumeIMAPI") static EYIMErrorcode Logout();
返回值：
- EYIMErrorcode：错误码，详细描述见错误码定义。
回调接口：
登出是异步操作，登出成功的标识是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：游戏包名。
返回值：
- EYIMErrorcode：错误码，详细描述见错误码定义。

登录应用时，登录IM系统

登录界面介绍

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

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

典型场景

世界频道聊天

进入应用后，调用加入频道接口，进入世界、公会、区域等需要进入的聊天频道。

应用需要为各个聊天频道设置一个唯一的频道ID。

成功进入频道后，发送频道消息，文本、语音消息等。

接口与参数
- JoinChatRoom：加入频道
- chatRoomID：请求加入的频道ID，仅支持数字、字母、下划线组成的字符串，区分大小写，长度限制为255字节。
返回值：
- EYIMErrorcode：错误码，详细描述见错误码定义。

用户私聊

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

调用流程查看发送文本消息，发送语音消息。

直播聊天室

用户集成直播SDK后，导入IM SDK。

初始化IM SDK。

登录IM 系统。

进入指定的聊天频道。

发送频道消息（例如：弹幕式），调用流程查看发送文本消息。

发送文本消息

点击发送按钮，调用发消息接口，将输入框中的内容发送出去。

发送出的消息出现在聊天框右侧。

表情消息可以将表情信息打包成Json格式发送。

相关接口与参数：
- SendTextMessage：发文字消息接口。
- receiverID：接收者ID，私聊传入用户ID，频道聊天传入频道ID。
- chatType：聊天类型,私聊传1，频道聊天传2；需要频道聊天得先成功进入频道后发文本消息，此频道内的成员才能接收到消息。
- text：聊天内容。
- attachParam：发送文本附加信息。
- requestID：消息序列号，用于校验一条消息发送成功与否的标识。
返回值：
- EYIMErrorcode：错误码，详细描述见错误码定义。
拓展功能：
发送消息时，可以将玩家头像、昵称、角色等级、vip等级等要素打包成json格式发送。

发送语音消息

按住语音按钮时，调用SendAudioMessage。

松开按钮，调用StopAudioMessage接口，发送语音消息。

按住过程若需要取消发送，调用CancleAudioMessage取消发送。

相关接口与参数：
- SendAudioMessage：发送语音消息接口。
- StopAudioMessage：结束录音接口。
- CancleAudioMessage：取消录音接口。
- receiverID：接收者ID（⽤户ID或者群ID）。
- chatType：消息类型，表示私聊还是频道消息。
- requestID：消息序列号，用于校验一条消息发送成功与否的标识。
- extraParam：发送语音消息附加信息，主要用于调用方特别需求。
返回值：
- EYIMErrorcode：错误码，详细描述见错误码定义。
代码示例与详细说明：
- Cocos2D-x示例。

接收消息

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

相关接口与参数：
- OnRecvMessage：收消息接口。
代码示例与详细说明：
- Cocos2D-x示例。

接收语音消息并播放

接收语音消息

通过GetMessageType()分拣出语音消息（MessageBodyType.Voice）。

⽤GetMessageID()获得消息ID。

点击语音气泡，调用DownloadFile接口下载语音文件。

调用方播放语音文件。

相关接口与参数：
- DownloadFile：下载语音文件接口。
- StartPlayAudio：播放语音文件接口。
  - messageID：消息ID。
  - savePath：语音文件保存路径。
  - path：待播放文件路径。
返回值：
- EYIMErrorcode：错误码，详细描述见错误码定义。
代码示例与详细说明：
- Cocos2D-x示例。

登出IM系统

更换账号

如下两种情况需要登出IM系统：

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

退出应用时，调用Logout接口登出IM系统。

相关接口：
- Logout：登出接口。
返回值：
- EYIMErrorcode：错误码，详细描述见错误码定义。

文档目录

IM SDK for UE4 开发指引

概述

IM SDK接口调用顺序

四步集成IM SDK

第一步 注册账号

第二步 添加游戏，获取Appkey

第三步 下载IM SDK包体

第四步 开发环境配置

快速接入

1. 导入IM SDK

2. 绑定回调类

绑定回调对象

3. 初始化

4. 登录IM系统

5. 进入聊天频道

6. 发送文本消息

7. 发送语音消息

8. 接收消息

9. 接收语音消息并播放

10. 登出IM系统

典型场景集成方案

启动应用，初始化IM SDK

登录应用时，登录IM系统

典型场景

世界频道聊天

用户私聊

直播聊天室

发送文本消息

发送语音消息

接收消息

接收语音消息并播放

登出IM系统

第一步注册账号

第二步添加游戏，获取Appkey

第三步下载IM SDK包体

第四步开发环境配置