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引擎。初始化接口的输入参数appKeyappSecurity需要根据实际申请得到的值进行替换, 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:若在频道被禁言,禁言结束时间
  • 拓展功能: 发送消息时,可以将玩家头像、昵称、角色等级、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,无论录音是否成功都会收到发送语音消息结果的回调OnSendAudioMessageStatusOnStartSendAudioMessage在接收时间上比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 int32& 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:若在频道被禁言,禁言结束时间
  • 备注: 此套接口是异步操作,发送语音消息成功的标识是收到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:发送语音消息附加信息,主要用于调用方特别需求
  • 返回值:

  • 代码示例与详细说明:
    • [Cocos2D-x示例](#7. 发送语音消息)

接收消息

接收消息

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

    • OnRecvMessage:收消息接口
  • 代码示例与详细说明:
    • [Cocos2D-x示例](#8. 接收消息)

接收语音消息并播放

接收语音消息

  • 通过GetMessageType()分拣出语音消息(MessageBodyType.Voice)
  • GetMessageID()获得消息ID
  • 点击语音气泡,调用DownloadFile接口下载语音文件
  • 调用方播放语音文件
  • 相关接口与参数:

    • DownloadFile:下载语音文件接口
    • StartPlayAudio:播放语音文件接口

    • messageID:消息ID
    • savePath:语音文件保存路径
    • path:待播放文件路径
  • 返回值:

  • 代码示例与详细说明:
    • [Cocos2D-x示例](#9. 接收语音消息并播放)

登出IM系统

更换账号

  • 如下两种情况需要登出IM系统:
  • 注销账号时,调用Logout接口登出IM系统
  • 退出应用时,调用Logout接口登出IM系统
  • 相关接口:

    • Logout:登出接口
  • 返回值: