游密即时通讯SDK(IM SDK)为玩家提供完整的游戏内互动服务,游戏开发者无需关注IM通讯复杂的内部工作流程,只需调用IM SDK提供的接口,即可快速实现世界聊天、公会聊天、组队聊天、文字、表情、语音等多项功能。
在游密官网注册游密账号。
在控制台添加游戏,获得接入需要的Appkey、Appsecret。
PrivateDependencyModuleNames.AddRange(new string[] { "YoumeIM" });
成功导入SDK后,需要使用SDK功能的关卡。首先创建一个继承 YoumeIMObserver 的对象来绑定至SDK, 用于接受SDK的回调事件。
创建一个蓝图对象继承 YoumeIMObserver , 在该对象的构造和析构函数处分别进行回调对象的绑定与解绑。
UFUNCTION(BlueprintCallable, Category = "YoumeIMAPI")
static void BindObserver(TScriptInterface<IYoumeIMObserver> Observer);
UFUNCTION(BlueprintCallable, Category = "YoumeIMAPI")
static void UnbindObserver();
需要在游戏开始前调用 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", "");
成功初始化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验证传入:""。返回值:
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
:错误码。登录成功后,如果有群组聊天需要,比如游戏里面的世界、工会、区域等,需要进入聊天频道,调用方为聊天频道设置一个唯一的频道ID,可以进入多个频道。
调用示例:
// 可在登录成功回调里面执行
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。在成功登录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
:消息序列号,用于校验一条消息发送成功与否的标识。返回值:
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。 在成功登录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
:发送语音消息附加信息,主要用于调用方特别需求。返回值:
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
同步返回值是Success才能收到回调;语音消息发送成功,接收方会收到OnRecvMessage
回调,能从该回调中下载语音文件。
- 通过
OnRecvMessage
接口被动接收消息,需要开发者实现。
调用示例:
GetMessageBody()->GetMessageType()
获取消息类型并进行相应处理。
- 通过
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
:待播放文件路径。返回值:
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
:文件路径。注销账号时,调用登出接口Logout
登出IM系统。
调用示例:
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系统。
应用启动的第一时间需要调用初始化接口。
接口与参数:
EYIMErrorcode
:错误码,详细描述见错误码定义。
- 点击
登录
按钮时,调用IM SDK登录接口。
接口与参数:
Login
:登录接口。userID
:由调⽤者分配,不可为空字符串,只可由字母或数字或下划线组成,用户首次登录会自动注册所用的用户ID和密码。passwd
:⽤户密码,不可为空字符串,由调用者分配,二次登录时需与首次登录一致,否则会报UsernamePasswordError。token
:用户验证token,可选,如不使用token验证传入:""。EYIMErrorcode
:错误码,详细描述见错误码定义。
- 进入应用后,调用加入频道接口,进入世界、公会、区域等需要进入的聊天频道。
- 应用需要为各个聊天频道设置一个唯一的频道ID。
- 成功进入频道后,发送频道消息,文本、语音消息等。
接口与参数
JoinChatRoom
:加入频道chatRoomID
:请求加入的频道ID,仅支持数字、字母、下划线组成的字符串,区分大小写,长度限制为255字节。EYIMErrorcode
:错误码,详细描述见错误码定义。
- 用户集成直播SDK后,导入IM SDK。
- 初始化IM SDK。
- 登录IM 系统。
- 进入指定的聊天频道。
- 发送频道消息(例如:弹幕式),调用流程查看发送文本消息。
- 点击发送按钮,调用发消息接口,将输入框中的内容发送出去。
- 发送出的消息出现在聊天框右侧。
- 表情消息可以将表情信息打包成Json格式发送。
相关接口与参数:
SendTextMessage
:发文字消息接口。receiverID
:接收者ID,私聊传入用户ID,频道聊天传入频道ID。chatType
:聊天类型,私聊传1
,频道聊天传2
;需要频道聊天得先成功进入频道后发文本消息,此频道内的成员才能接收到消息。text
:聊天内容。attachParam
:发送文本附加信息。requestID
:消息序列号,用于校验一条消息发送成功与否的标识。返回值:
EYIMErrorcode
:错误码,详细描述见错误码定义。
- 按住语音按钮时,调用
SendAudioMessage
。- 松开按钮,调用
StopAudioMessage
接口,发送语音消息。- 按住过程若需要取消发送,调用
CancleAudioMessage
取消发送。
相关接口与参数:
SendAudioMessage
:发送语音消息接口。StopAudioMessage
:结束录音接口。CancleAudioMessage
:取消录音接口。
receiverID
:接收者ID(⽤户ID或者群ID)。chatType
:消息类型,表示私聊还是频道消息。requestID
:消息序列号,用于校验一条消息发送成功与否的标识。extraParam
:发送语音消息附加信息,主要用于调用方特别需求。返回值:
EYIMErrorcode
:错误码,详细描述见错误码定义。
- 通过
OnRecvMessage
接口被动接收消息,需要开发者实现,接收消息进行相应的展示,如果是语音消息需要下载语音,以及下载完成后的语音播放。
相关接口与参数:
OnRecvMessage
:收消息接口。
- 通过
GetMessageType()
分拣出语音消息(MessageBodyType.Voice)
。- ⽤
GetMessageID()
获得消息ID。- 点击语音气泡,调用
DownloadFile
接口下载语音文件。- 调用方播放语音文件。
相关接口与参数:
DownloadFile
:下载语音文件接口。StartPlayAudio
:播放语音文件接口。
messageID
:消息ID。savePath
:语音文件保存路径。path
:待播放文件路径。返回值:
EYIMErrorcode
:错误码,详细描述见错误码定义。
- 如下两种情况需要登出IM系统:
- 注销账号时,调用
Logout
接口登出IM系统。- 退出应用时,调用
Logout
接口登出IM系统。
相关接口:
Logout
:登出接口。EYIMErrorcode
:错误码,详细描述见错误码定义。