IM SDK for UE4 使用指南

导入IM SDK

插件配置

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

基本接口使用时序图

基本接口使用时序图

初始化

绑定回调对象

创建一个蓝图对象继承 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", "");

回调接口

继承 YoumeIMObserver 之后在 Interfaces 界面下有各类功能的回调接口, 只要继承这些方法就可以监听到SDK的回调。

重连回调

开始重连回调

  • 原型：

    UFUNCTION(BlueprintNativeEvent, BlueprintCallable, Category = "YoumeIM Notice")
void OnStartReconnect();

重连结果回调

  • 原型：

    UFUNCTION(BlueprintNativeEvent, BlueprintCallable, Category = "YoumeIM Notice")
void OnRecvReconnectResult(const EReconnectResult& result);
  • 参数：
    result：重连结果，枚举类型，
    RECONNECTRESULT_SUCCESS=0 //重连成功
    RECONNECTRESULT_FAIL_AGAIN=1 //重连失败，再次重连
    RECONNECTRESULT_FAIL=2 //最终重连失败

录音音量回调

音量值范围:0~1, 频率:1s ios 约2次，android 约8次。

  • 原型：

    UFUNCTION(BlueprintNativeEvent, BlueprintCallable, Category = "YoumeIM Message")
void OnRecordVolumeChange(const float& volume);
  • 参数：
    volume：音量值。

用户管理

用户登录

完成以上的步骤后就可以使用IM功能了，IM用户登录IM后台服务器后即可以正常收发消息。通过UYoumeIMAPI的Login接口登录IM，需要用户提供用户名、密码。登录为异步过程，通过回调函数返回是否成功，成功后方能进行后续操作。 用户首次登录会自动注册，如果后台已存在此用户名，则会校验密码是否与第一次相同（用户名和密码的格式见下方相关参数说明）。

  • 原型：

      UFUNCTION(BlueprintCallable, Category = "YoumeIMAPI")
  static EEYIMErrorcode Login(const FString userID, const FString password, const FString token);

  • 参数说明：
    userID：用户ID，由调用者分配，不可为空字符串，只可由字母或数字或下划线组成，长度限制为255字节。
    passwd：用户密码，不可为空字符串，如无特殊要求可以设置为固定字符串。
    token：使用服务器token验证模式时使用该参数，否则使用空字符串：""，由restAPI获取token值。

  • 返回值：
    EYIMErrorcode：错误码，详细描述见错误码定义。

  • 回调接口：

    UFUNCTION(BlueprintNativeEvent, BlueprintCallable, Category = "YoumeIM Login")
void OnLogin(const EEYIMErrorcode& errorcode, const FString& userID);
  • 回调参数：
    errorcode：错误码。
    userID：用户ID。

用户登出

如用户主动退出或需要进行用户切换，则需要调用登出操作，通过UYoumeIMAPI的Logout接口登出。

  • 原型：

      UFUNCTION(BlueprintCallable, Category = "YoumeIMAPI")
  static EEYIMErrorcode Logout();

  • 参数：
    无。

  • 返回：
    EYIMErrorcode：错误码，详细描述见错误码定义。

  • 回调接口：

    UFUNCTION(BlueprintNativeEvent, BlueprintCallable, Category = "YoumeIM Login")
void OnLogout(const EYIMErrorcode& errorcode);
  • 回调参数：
    errorcode：错误码。

被用户踢出通知

同一个用户ID在多台设备上登录时，后登录的会把先登录的踢下线，收到OnKickOff()通知。

  • 原型：

    UFUNCTION(BlueprintNativeEvent, BlueprintCallable, Category = "YoumeIM Login")
void OnKickOff();

用户信息

设置用户的详细信息

通过UYoumeIMAPI的SetUserInfo接口设置用户信息后，在游密消息管理后台才能看到消息发送者的详细信息。

  • 原型：

    UFUNCTION(BlueprintCallable, Category = "YoumeIMAPI")
static EYIMErrorcode SetUserInfo(const FString nickName, const FString serverAreaID, const FString serverArea, const FString locationID, const FString location, const FString level, const FString vipLevel);

  • 参数：
    nickName：用户昵称。
    serverAreaID：游戏服ID。
    serverArea：游戏服名称。
    locationID：游戏大区ID。
    location：游戏大区名。
    level：角色等级。
    vipLevel：玩家VIP等级。

  • 返回值：
    EYIMErrorcode：错误码，详细描述见错误码定义。

获取指定用户的详细信息

可通过UYoumeIMAPI的GetUserInfo接口获取指定用户的详细信息。

  • 原型：

    UFUNCTION(BlueprintCallable, Category = "YoumeIMAPI")
static EYIMErrorcode GetUserInfo(const FString userID);

  • 参数：
    userID： 要查询的用户ID。

  • 返回值：
    EYIMErrorcode：错误码，详细描述见错误码定义。

  • 回调接口：

    UFUNCTION(BlueprintNativeEvent, BlueprintCallable, Category = "YoumeIM Contact")
void OnGetUserInfo(const EYIMErrorcode& errorcode, const FString& userID, const FString& nickName, const FString& serverAreaID, const FString& serverArea, const FString& locationID, const FString& location, const FString& level, const FString& vipLevel);
  • 参数：
    errorcode：错误码。
    userID：用户ID。
    nickName：用户昵称。
    serverAreaID：游戏服ID。
    serverArea：游戏服名称。
    locationID：游戏大区ID。
    location：游戏大区名。
    level：角色等级。
    vipLevel：玩家VIP等级。

查询用户在线状态

可通过UYoumeIMAPI的QueryUserStatus接口查询用户的在线状态。

  • 原型：

    UFUNCTION(BlueprintCallable, Category = "YoumeIMAPI")
static EYIMErrorcode QueryUserStatus(const FString userID);

  • 参数：
    userID：要查询的用户ID。

  • 返回值：
    EYIMErrorcode：错误码，详细描述见错误码定义。

  • 回调接口：

    UFUNCTION(BlueprintNativeEvent, BlueprintCallable, Category = "YoumeIM Contact")
void OnQueryUserStatus(const EYIMErrorcode& errorcode, const FString& userID, const EYIMUserStatus& status);
  • 回调参数：
    errorcode：错误码，查询请求是否成功的通知。
    userID：查询的用户ID。
    status：登录状态，枚举类型， UserStatus.STATUS_ONLINE=0 //在线 UserStatus.STATUS_OFFLINE=1 //离线
    （如查询的用户ID是未注册的，用户状态返回的是离线状态）

频道管理

加入频道

通过UYoumeIMAPI的JoinChatRoom接口加入聊天频道，如果频道不存在则后台自动创建。有了这个ID就可以收发频道消息。开发者要保证频道号全局唯一，以避免用户进入错误频道。结果需要在开发者实现IYoumeIMObserver的OnJoinChatRoom里处理。

  • 原型：

    UFUNCTION(BlueprintCallable, Category = "YoumeIMAPI Room")
static EYIMErrorcode JoinChatRoom(const FString chatRoomID);

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

  • 返回值：
    EYIMErrorcode：错误码，详细描述见错误码定义。

  • 回调接口：

    UFUNCTION(BlueprintNativeEvent, BlueprintCallable, Category = "YoumeIM Room")
void OnJoinChatRoom(const EYIMErrorcode& errorcode, const FString& chatRoomID);
  • 回调参数：
    errorcode：错误码，详细描述见错误码定义。 strChatRoomID：频道ID。

离开频道

通过UYoumeIMAPI的LeaveChatRoom接口离开频道。

  • 原型：

    UFUNCTION(BlueprintCallable, Category = "YoumeIMAPI Room")
static EYIMErrorcode LeaveChatRoom(const FString chatRoomID);

  • 参数：
    strChatRoomID：请求离开的频道ID。

  • 返回值：
    EYIMErrorcode：错误码，详细描述见错误码定义。

  • 回调接口：

    UFUNCTION(BlueprintNativeEvent, BlueprintCallable, Category = "YoumeIM Room")
void OnLeaveChatRoom(const EYIMErrorcode& errorcode, const FString& chatRoomID);
  • 回调参数：
    errorcode：错误码，详细描述见错误码定义。
    chatRoomID：频道ID。

离开所有频道

通过UYoumeIMAPI的LeaveAllChatRooms接口离开所有频道。

  • 原型：

    UFUNCTION(BlueprintCallable, Category = "YoumeIMAPI Room")
static EYIMErrorcode LeaveAllChatRooms();

  • 返回值：
    EYIMErrorcode：错误码，详细描述见错误码定义。

  • 回调接口：

    UFUNCTION(BlueprintNativeEvent, BlueprintCallable, Category = "YoumeIM Room")
void OnLeaveAllChatRooms(const EYIMErrorcode& errorcode);
  • 参数：
    errorcode：错误码。

用户进出频道通知

此功能默认不开启，需要的请联系我们开启此服务。联系我们，可以通过专属游密支持群或者技术支持的大群。

小频道(小于100人)内，当其他用户进入频道，会收到OnUserJoinChatRoom通知。

  • 原型：

    UFUNCTION(BlueprintNativeEvent, BlueprintCallable, Category = "YoumeIM Room")
void OnUserJoinChatRoom(const FString& chatRoomID, const FString& userID);
  • 参数：
    chatRoomID：频道ID。
    userID：用户ID。

小频道(小于100人)内，当其他用户退出频道，会收到OnUserLeaveChatRoom通知。

  • 原型：

    UFUNCTION(BlueprintNativeEvent, BlueprintCallable, Category = "YoumeIM Room")
void OnUserLeaveChatRoom(const FString& chatRoomID, const FString& userID);
  • 参数：
    chatRoomID：频道ID。
    userID：用户ID。

获取房间成员数量

可通过UYoumeIMAPI的GetRoomMemberCount接口获取进入频道的用户数量。

  • 原型：

    UFUNCTION(BlueprintCallable, Category = "YoumeIMAPI Room")
static EYIMErrorcode GetRoomMemberCount(const FString chatRoomID);

  • 参数：
    chatRoomID：频道ID(已成功加入此频道才能获取该频道的人数)。

  • 返回值：
    EYIMErrorcode：错误码，详细描述见错误码定义。

  • 回调接口：

    UFUNCTION(BlueprintNativeEvent, BlueprintCallable, Category = "YoumeIM Room")
void OnGetRoomMemberCount(const EYIMErrorcode& errorcode, const FString& chatRoomID, const int32& count);
  • 回调参数：
    errorcode：错误码。
    chatRoomID：频道ID。
    count：频道中的成员数量。

消息管理

接收消息

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

  • 原型：

    UFUNCTION(BlueprintNativeEvent, BlueprintCallable, Category = "YoumeIM Message")
void OnRecvMessage(UYIMMessage* message);

  • 参数：
    pMessage：消息。

  • 备注：
    UYIMMessage 消息基类成员方法如下：
    GetSenderID()：消息发送者ID。
    GetReceiveID()：消息接收者ID。
    GetChatType()：聊天类型，私聊/频道聊天/群发消息。
    GetMessageID()：消息ID。
    GetMessageBody()->GetMessageType()：消息类型，枚举类型，
    MessageBodyType_Unknow = 0, //未知类型
    MessageBodyType_TXT = 1, //文本消息
    MessageBodyType_CustomMesssage = 2, //自定义消息
    MessageBodyType_Emoji = 3, //表情
    MessageBodyType_Image = 4, //图片
    MessageBodyType_Voice = 5, //语音 MessageBodyType_Video = 6, //视频
    MessageBodyType_File = 7, //文件
    MessageBodyType_Gift = 8 //礼物
    GetCreateTime()：消息发送时间。
    GetDistance()：若是附近频道的消息，此值是该消息用户与自己的地理位置距离。
    IsRead()：消息是否已读。

    UYIMMessageBodyText继承UYIMMessageBodyBase类，类成员如下：
    GetMessageContent()：文本消息内容。
    GetAttachParam()： 发送文本附件信息。

    UYIMMessageBodyCustom继承UYIMMessageBodyBase类，类成员如下：
    GetCustomMessage()：自定义消息内容。

    UYIMMessageBodyFile继承UYIMMessageBodyBase类，类成员如下：
    GetFileName()：文件名。
    GetFileType()：文件类型，枚举类型，
    FileType_Other = 0 //其它
    FileType_Audio = 1 //音频（语音）
    FileType_Image = 2 //图片
    FileType_Video = 3 //视频
    GetFileSize()：文件大小。
    GetFileExtension()：文件扩展信息。
    GetExtraParam()：附加信息。
    GetLocalPath()：文件路径。

    UYIMMessageGift继承UYIMMessageBodyBase类，类成员如下：
    GetAnchor()：主播ID。
    GetGiftID()：礼物ID。
    GetGiftCount()：礼物数量。
    GetExtraParam()：附加参数。

    UYIMMessageBodyAudio继承UYIMMessageBodyBase类，类成员如下：
    GetText()：若使用的是语音转文字录音，此值为语音识别的文本内容，否则是""。
    GetAudioTime()：语音时长（单位：秒）。
    GetExtraParam()：发送语音时的附加参数。
    GetFileSize()：语音文件大小（单位：字节）。
    GetLocalPath()：语音文件本地存放路径。
    IsPlayed()：语音是否已播放，true-已播放，false-未播放。

  • 示例：

发送文本消息

可通过UYoumeIMAPI的SendTextMessage接口发送文本消息。异步返回结果通过IYoumeIMObserver的OnSendMessageStatus接口返回。

  • 原型：

      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：聊天类型，私聊/频道聊天。
    text：聊天内容。
    attachParam：发送文本附加信息。
    requestID：消息序列号，用于校验一条消息发送成功与否的标识。

  • 返回值：
    EYIMErrorcode：错误码，详细描述见错误码定义。

  • 回调接口：

    UFUNCTION(BlueprintNativeEvent, BlueprintCallable, Category = "YoumeIM Message")
void OnSendMessageStatus(const int64& requestID, const EYIMErrorcode& errorcode, const int64& sendTime, const bool isForbidRoom, const int32& reasonType, const int64& forbidEndTime, const int64& messageID);
  • 回调参数：
    requestID：消息序列号，用于校验一条消息发送成功与否的标识。
    errorcode：错误码，详细描述见错误码定义。
    sendTime：消息发送时间。
    isForbidRoom：若发送的是频道消息，显示在此频道是否被禁言，true-被禁言，false-未被禁言（errorcode为禁言才有效）。
    reasonType：若在频道被禁言，禁言原因类型，0-未知，1-发广告，2-侮辱，3-政治敏感，4-恐怖主义，5-反动，6-色情，7-其它（errorcode为禁言才有效）。
    forbidEndTime：若在频道被禁言，禁言结束时间（errorcode为禁言才有效）。
    messageID：服务器返回的消息id。

群发文本消息

可通过UYoumeIMAPI的MultiSendTextMessage接口群发文本消息，每次不要超过200个用户。

  • 原型：

    UFUNCTION(BlueprintCallable, Category = "YoumeIMAPI Message")
static EYIMErrorcode MultiSendTextMessage(TArray<FString> vecReceiver, const FString text);

  • 参数：
    vecReceiver：接受消息的用户id列表。
    text：文本消息内容。

  • 返回值：
    EYIMErrorcode：错误码，详细描述见错误码定义。

发送礼物消息

可通过UYoumeIMAPI的SendGift接口给主播发送礼物消息，支持在游密主播后台查看礼物消息信息和统计信息。客户端还是通过OnRecvMessage接收消息。

  • 原型：

    UFUNCTION(BlueprintCallable, Category = "YoumeIMAPI Message")
static EYIMErrorcode SendGift(const FString anchorID, const FString channel, int32 giftId, int32 giftCount, const FString nickName, const FString serverArea, const FString location, const FString score, const FString level, const FString vipLevel, const FString extra, int64& requestID);

  • 参数：
    anchorID：游密后台设置的对应的主播游戏id。
    channel：主播所进入的频道ID，通过JoinChatRoom进入此频道的用户可以接收到消息。
    giftId：礼物物品id，特别的是0表示只是留言。
    giftCount：礼物物品数量。
    extraParam：扩展内容json字符串，目前要求包含如下字段： {"nickname":"","server_area":"","location":"","score":"","level":"","vip_level":"","extra":""}。
    requestID：消息序列号。

  • 返回值：
    EYIMErrorcode：错误码，详细描述见错误码定义。

  • 回调接口：

    UFUNCTION(BlueprintNativeEvent, BlueprintCallable, Category = "YoumeIM Message")
void OnSendMessageStatus(const int64& requestID, const EYIMErrorcode& errorcode, const int64& sendTime, const bool isForbidRoom, const int32& reasonType, const int64& forbidEndTime, const int64& messageID);
  • 回调参数：
    requestID：消息序列号，用于校验一条消息发送成功与否的标识。
    errorcode：错误码，详细描述见错误码定义。
    sendTime：消息发送时间。
    isForbidRoom：若发送的是频道消息，显示在此频道是否被禁言，true-被禁言，false-未被禁言（errorcode为禁言才有效）。
    reasonType：若在频道被禁言，禁言原因类型，0-未知，1-发广告，2-侮辱，3-政治敏感，4-恐怖主义，5-反动，6-色情，7-其它（errorcode为禁言才有效）。
    forbidEndTime：若在频道被禁言，禁言结束时间（errorcode为禁言才有效）。
    messageID：服务器返回的消息id。

发送自定义消息

可通过UYoumeIMAPI的SendCustomMessage接口发送自定义消息。异步返回结果通过IYoumeIMObserver的OnSendMessageStatus接口返回。注意：自定义消息可能包含\0终止符，发送和接收时都需要注意。

  • 原型：

    UFUNCTION(BlueprintCallable, Category = "YoumeIMAPI Message")
static EYIMErrorcode SendCustomMessage(const FString receiverID, EYIMChatType chatType, const FString content, int32 size, int64& requestID);

  • 参数：
    receiverID：接收者（用户ID或者频道ID）。
    chatType：聊天类型，私聊/频道聊天。
    content：自定义消息内容， 可以包含\0终止符。
    size：自定义消息内容长度。
    requestID：消息序列号，用于校验一条消息发送成功与否的标识。

  • 返回值：
    EYIMErrorcode：错误码，详细描述见错误码定义。

  • 回调通知接口：

    UFUNCTION(BlueprintNativeEvent, BlueprintCallable, Category = "YoumeIM Message")
void OnSendMessageStatus(const int64& requestID, const EYIMErrorcode& errorcode, const int64& sendTime, const bool isForbidRoom, const int32& reasonType, const int64& forbidEndTime, const int64& messageID);
  • 回调参数：
    requestID：消息序列号，用于校验一条消息发送成功与否的标识。
    errorcode：错误码，详细描述见错误码定义。
    sendTime：消息发送时间。
    isForbidRoom：若发送的是频道消息，显示在此频道是否被禁言，true-被禁言，false-未被禁言（errorcode为禁言才有效）。
    reasonType：若在频道被禁言，禁言原因类型，0-未知，1-发广告，2-侮辱，3-政治敏感，4-恐怖主义，5-反动，6-色情，7-其它（errorcode为禁言才有效）。
    forbidEndTime：若在频道被禁言，禁言结束时间（errorcode为禁言才有效）。
    messageID：服务器返回的消息id。

发送文件消息

发送文件

可通过UYoumeIMAPI的SendFile接口发送文件消息。

  • 原型：

    UFUNCTION(BlueprintCallable, Category = "YoumeIMAPI Message")
static EYIMErrorcode SendFile(const FString receiverID, EYIMChatType chatType, const FString filePath, const FString extraParam, EYIMFileType fileType, int64& requestID);

  • 参数：
    receiverID：接收方id。
    chatType：聊天类型，私聊/频道。
    filePath：要发送的文件绝对路径，包括文件名。
    extraParam：额外信息，格式自己定义，自己解析。
    fileType：文件类型，枚举类型，
    FileType.FileType_Other=0 //其它
    FileType.FileType_Audio=1 //音频
    FileType.FileType_Image=2 //图片
    FileType.FileType_Video=3 //视频
    requestID：消息序列号。

  • 返回值：
    EYIMErrorcode：错误码，详细描述见错误码定义。

  • 回调通知接口：

    UFUNCTION(BlueprintNativeEvent, BlueprintCallable, Category = "YoumeIM Message")
void OnSendMessageStatus(const int64& requestID, const EYIMErrorcode& errorcode, const int64& sendTime, const bool isForbidRoom, const int32& reasonType, const int64& forbidEndTime, const int64& messageID);
  • 回调参数：
    requestID：消息序列号，用于校验一条消息发送成功与否的标识。
    errorcode：错误码，详细描述见错误码定义。
    sendTime：发送时间。
    isForbidRoom：是否房间被禁言，true房间被禁言，false玩家被禁言（errorcode为禁言才有效）。
    reasonType：禁言原因，参见YIMForbidSpeakReason（errorcode为禁言才有效）。
    forbidEndTime：禁言截止时间戳（errorcode为禁言才有效）。
    messageID：服务器返回的消息id。

下载文件

接收消息接口参考收消息通过GetMessageType()分拣出文件消息类型：MessageBodyType_File，用GetMessageID()获得消息ID。然后调用UYoumeIMAPI的DownloadFile接口下载文件。

  • 原型：

    UFUNCTION(BlueprintCallable, Category = "YoumeIMAPI Message")
static EYIMErrorcode DownloadFile(const FString downloadURL, const FString savePath, EYIMFileType fileType);

  • 参数：
    messageID：消息ID。
    savePath：文件保存路径（带文件名的全路径），比如"/sdcard/test.wav"如果目录不存在，SDK会自动创建。

  • 返回值：
    EYIMErrorcode：错误码，详细描述见错误码定义。

  • 回调接口：

    UFUNCTION(BlueprintNativeEvent, BlueprintCallable, Category = "YoumeIM Download")
void OnDownload(const EYIMErrorcode& errorcode, UYIMMessage* message, const FString& savePath);
  • 回调参数：
    msg：消息结构，IYIMMessage消息基类详细，查看 接收消息备注。
    errorcode：下载结果错误码。
    savePath：保存路径，如果没有权限问题，SDK会尝试自动创建。

语音消息管理

语音消息聊天简要流程：

  • 调用SendAudioMessage方法就开始录音，StopAudioMessage表示结束录音并发送，CancleAudioMessage表示取消本次录音发送。
  • 接收方接收语音消息通知后，调用方控制是否下载，调用下载接口就可以下载音频文件。
  • 开发者调用播放接口播放wav音频文件。

设置是否自动下载语音消息

可通过UYoumeIMAPI的SetDownloadAudioMessageSwitch接口设置是否自动下载语音消息。
SetDownloadAudioMessageSwitch()在初始化之后，启动语音之前调用;若设置了自动下载语音消息，不需再调用DownloadMessage接口，收到语音消息时会自动下载，自动下载完成也会收到DownloadMessage接口对应的OnDownload()回调。

  • 原型：

    UFUNCTION(BlueprintCallable, Category = "YoumeIMAPI Message")
static EYIMErrorcode SetDownloadAudioMessageSwitch(bool download);

  • 参数：
    download：true-自动下载语音消息，false-不自动下载语音消息(默认)。

  • 返回值：
    EYIMErrorcode：错误码，详细描述见错误码定义。

设置语音识别的语言

SendAudioMessage提供语音识别功能，将语音识别为文字，默认输入语音为普通话，识别文字为简体中文，可通过UYoumeIMAPI的SetSpeechRecognizeLanguage函数设置语音识别的语言。此服务需要联系我们进行配置。

  • 原型：

    UFUNCTION(BlueprintCallable, Category = "YoumeIMAPI Message")
static EYIMErrorcode SetSpeechRecognizeLanguage(ESpeechLanguage language);

  • 参数：
    language：语言，枚举类型，
    SPEECHLANG_MANDARIN=0 //普通话
    SPEECHLANG_YUEYU=1 //粤语
    SPEECHLANG_SICHUAN=2 //四川话（windows不支持）
    SPEECHLANG_HENAN=3 //河南话（只支持iOS）
    SPEECHLANG_ENGLISH=4 //英语
    SPEECHLANG_TRADITIONAL=5 //繁体中文

  • 返回值：
    EYIMErrorcode：错误码，详细描述见错误码定义。

发送语音消息

启动录音

可通过UYoumeIMAPI的SendAudioMessage接口发送带文字识别的语音消息，调用StopAudioMessage接口后自动停止录音并发送，或者调用CancleAudioMessage取消本次消息发送。 注意：语音消息最大的时长是1分钟（超过1分钟就自动发送）

  • 原型：

    UFUNCTION(BlueprintCallable, Category = "YoumeIMAPI Message")
static EYIMErrorcode SendAudioMessage(const FString receiverID, EYIMChatType chatType, int64& requestID);

  • 参数：
    receiverID：接收者ID，私聊传入用户ID，频道聊天传入频道ID。
    chatType：聊天类型，私聊/频道聊天。
    requestID：消息序列号，用于校验一条消息发送成功与否的标识。

  • 返回值：
    EYIMErrorcode：错误码，详细描述见错误码定义。

  • 原型：

      //可通过`UYoumeIMAPI`的`SendOnlyAudioMessage`接口发送不带文字识别的语音消息，调用`StopAudioMessage`接口后自动停止录音并发送，或者调用`CancleAudioMessage`取消本次消息发送。    
UFUNCTION(BlueprintCallable, Category = "YoumeIMAPI Message")
static EYIMErrorcode SendOnlyAudioMessage(const FString receiverID, EYIMChatType chatType, int64& requestID);

  • 参数：
    receiverID：接收者ID，私聊传入用户ID，频道聊天传入频道ID。
    chatType：聊天类型，私聊/频道聊天。
    requestID：消息序列号，用于校验一条消息发送成功与否的标识。

  • 返回值：
    EYIMErrorcode：错误码，详细描述见错误码定义。
结束录音并发送

可通过UYoumeIMAPI的StopAudioMessage结束录音并发送录音文件。

  • 原型：

    UFUNCTION(BlueprintCallable, Category = "YoumeIMAPI Message")
static EYIMErrorcode StopAudioMessage(const FString extraParam);

  • 参数：
    extraParam：发送语音消息的附加参数，格式自定义，自己解析 （json、xml...），可为空字符串。

  • 返回值：
    EYIMErrorcode：错误码，详细描述见错误码定义。

  • 回调接口： 结束录音并发送接口对应两个回调接口，若语音成功发送出去能得到两个回调通知，语音发送失败则只会得到发送语音结果回调。 

    // 开始上传语音回调，（调用StopAudioMessage停止语音之后，成功发送语音消息之前），录音结束，开始发送录音的通知，这个时候已经可以拿到语音文件进行播放
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);

  • 参数：
    errorcode：错误码，Success 或者 PTT_ReachMaxDuration 均表示成功。
    requestID：消息序列号，用于校验一条消息发送成功与否的标识。
    text：语音转文字识别的文本内容，如果没有用带语音转文字的接口，该字段为空字符串。
    audioPath：录音生成的wav文件的本地完整路径，比如"/sdcard/xxx/xxx.wav"。
    audioTime：录音时长（单位为秒）。

    sendTime：语音发送时间。
    isForbidRoom：若发送的是频道消息，表示在此频道是否被禁言，true-被禁言，false-未被禁言（errorcode为禁言才有效）。
    reasonType：禁言原因，0-未知，1-发广告，2-侮辱，3-政治敏感，4-恐怖主义，5-反动，6-色情，7-其它（errorcode为禁言才有效）。
    forbidEndTime：禁言截止时间戳（errorcode为禁言才有效）。

取消本次录音

可通过UYoumeIMAPI的CancleAudioMessage接口取消语音。

  • 原型：

    UFUNCTION(BlueprintCallable, Category = "YoumeIMAPI Message")
static EYIMErrorcode CancleAudioMessage();
  • 返回值：
    EYIMErrorcode：错误码，详细描述见错误码定义。

接收语音消息

接收消息接口参考收消息通过GetMessageType()分拣出语音消息类型：MessageBodyType_Voice，用GetMessageID()获得消息ID。然后调用UYoumeIMAPI的DownloadMessage接口下载语音消息，然后调用方播放该文件。

  • 原型：

    //下载收到的语音消息文件
UFUNCTION(BlueprintCallable, Category = "YoumeIMAPI Message")
static EYIMErrorcode DownloadMessage(int64 messageID, const FString savePath);

  • 参数：
    messageID：消息ID。
    savePath：文件保存路径（带文件名的全路径），比如"/sdcard/test.wav"如果目录不存在，SDK会自动创建。

  • 返回值：
    EYIMErrorcode：错误码，详细描述见错误码定义。

  • 回调接口：

    UFUNCTION(BlueprintNativeEvent, BlueprintCallable, Category = "YoumeIM Download")
void OnDownload(const EYIMErrorcode& errorcode, UYIMMessage* message, const FString& savePath);
  • 回调参数：
    msg：消息结构，IYIMMessage消息基类详细，查看 接收消息备注。
    errorcode：下载结果错误码。
    savePath：保存路径，如果没有权限问题，SDK会尝试自动创建。

语音播放

播放语音

可通过UYoumeIMAPI的StartPlayAudio接口播放语音文件，目前只支持WAV格式。

  • 原型：

    UFUNCTION(BlueprintCallable, Category = "YoumeIMAPI")
static EYIMErrorcode StartPlayAudio(const FString path);

  • 参数：
    path： 音频文件绝对路径。

  • 返回值：
    EYIMErrorcode：错误码，详细描述见错误码定义。

  • 回调接口：

    UFUNCTION(BlueprintNativeEvent, BlueprintCallable, Category = "YoumeIM AudioPlay")
void OnPlayCompletion(const EYIMErrorcode& errorcode, const FString& path);
  • 参数：
    errorcode：错误码，errorcode == Success表示正常播放结束，errorcode == PTT_CancelPlay表示播放到中途被打断。
    path：被播放的音频文件地址。
停止语音播放

可通过UYoumeIMAPI的StopPlayAudio接口停止播放语音文件。

  • 原型：

    UFUNCTION(BlueprintCallable, Category = "YoumeIMAPI")
static EYIMErrorcode StopPlayAudio();
  • 返回值：
    EYIMErrorcode：错误码，详细描述见错误码定义。
设置语音播放音量

可通过UYoumeIMAPI的SetVolume接口设置语音的播放音量。

  • 原型：

    UFUNCTION(BlueprintCallable, Category = "YoumeIMAPI")
static void SetVolume(float volume);
  • 参数：
    volume：音量值，取值范围0.0f - 1.0f，默认值为 1.0f。
查询播放状态

可通过UYoumeIMAPI的IsPlaying接口查询播放状态。

  • 原型：

    UFUNCTION(BlueprintCallable, Category = "YoumeIMAPI")
static bool IsPlaying();
  • 返回值：
    是否正在播放,true正在播放，false没在播放。

录音缓存

设置录音缓存目录

可通过UYoumeIMAPI的SetAudioCacheDir接口设置录音的缓存目录，如果没有设置，SDK会在APP默认缓存路径下创建一个文件夹用于保存音频文件。 该接口建议初始化之后立即调用 。

  • 原型：

    UFUNCTION(BlueprintCallable, Category = "YoumeIMAPI")
void SetAudioCacheDir(const FString audioCacheDir);
  • 参数：
    audioCacheDir：缓存录音文件的文件夹路径，如果目录不存在，SDK会自动创建。
获取当前设置的录音缓存目录

可通过UYoumeIMAPI的GetAudioCachePath接口获取当前设置的录音缓存目录。

  • 原型：

    UFUNCTION(BlueprintCallable, Category = "YoumeIMAPI")
static FString GetAudioCachePath();
  • 返回值：
    返回当前设置的录音缓存目录的完整路径,std::string型。
清空录音缓存目录

可通过UYoumeIMAPI的ClearAudioCachePath接口 清理语音缓存目录(注意清空语音缓存目录后历史记录中会无法读取到音频文件，调用清理历史记录接口也会自动删除对应的音频缓存文件)。

  • 原型：

    UFUNCTION(BlueprintCallable, Category = "YoumeIMAPI")
static bool ClearAudioCachePath();
  • 返回值：
    true：表示清理成功，false：表示清理操作失败。

设置下载保存目录

可通过UYoumeIMAPI的SetDownloadDir接口设置下载的保存目录。下载保存目录是DownloadFile/DownloadMessage的默认下载目录，对下载语音消息和文件均适用；设置下载保存目录在初始化之后，启动语音之前调用，若设置了下载保存目录，调用UYoumeIMAPI的DownloadFile/DownloadMessage接口时，其中的savePath参数可以为空字符串（若savePath参数为空字符串时，下载语音消息和文件会生成以时间戳为前缀的文件）。

  • 原型：

    UFUNCTION(BlueprintCallable, Category = "YoumeIMAPI Message")
static EYIMErrorcode SetDownloadDir(const FString savePath);

  • 参数：
    path：下载目录路径，必须保证该路径可写。

  • 返回值：
    EYIMErrorcode：错误码，详细描述见错误码定义。

设置只识别语音文字

可通过UYoumeIMAPI的SetOnlyRecognizeSpeechText接口设置只识别语音文字。此功能是为了只获取语音识别的文字，不发送语音消息，接口调用与发送语音消息相同，但在成功录音后仅会收到识别的语音文本通知,不会收到OnSendAudioMessage回调。 实现只识别语音文字功能的接口调用顺序：SetOnlyRecognizeSpeechText->SendAudioMessage->StopAudioMessage->OnGetRecognizeSpeechText

  • 原型：

    UFUNCTION(BlueprintCallable, Category = "YoumeIMAPI Message")
static EYIMErrorcode SetOnlyRecognizeSpeechText(bool recognition);

  • 参数：
    recognition：true-只识别语音文字，false-识别语音文字并发送语音消息。

  • 返回值：
    EYIMErrorcode：错误码，详细描述见错误码定义。

  • 获取语音识别文本的回调接口：

    UFUNCTION(BlueprintNativeEvent, BlueprintCallable, Category = "YoumeIM Message")
void OnGetRecognizeSpeechText(const int64& requestID, const EYIMErrorcode& errorcode, const FString& text);
  • 回调参数：
    requestID：序列号。
    errorcode：错误码。
    text：返回的语音识别文本内容。

将接收的语音消息标记为已播放

可通过UYoumeIMAPI的SetVoiceMsgPlayed接口将接收的语音消息标记为已播放。

  • 原型：

    UFUNCTION(BlueprintCallable, Category = "YoumeIMAPI Message")
static EYIMErrorcode SetVoiceMsgPlayed(int64 messageID, bool played);

  • 参数：
    messageID：语音消息ID。
    played：是否已播放，true为已播放，false为未播放。

  • 返回值：
    EYIMErrorcode：错误码，详细描述见错误码定义

获取麦克风状态

可通过UYoumeIMAPI的GetMicrophoneStatus接口获取麦克风的状态。（该接口会临时占用麦克风）

  • 原型：

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

  • 回调接口：

    UFUNCTION(BlueprintNativeEvent, BlueprintCallable, Category = "YoumeIM AudioPlay")
void OnGetMicrophoneStatus(const EAudioDeviceStatus& status);
  • 回调参数：
    status：麦克风状态值，枚举类型，
    STATUS_AVAILABLE=0 //可用
    STATUS_NO_AUTHORITY=1 //无权限
    STATUS_MUTE=2 //静音
    STATUS_UNAVAILABLE=3 // 不可用

录音上传

启动录音

可通过UYoumeIMAPI的StartAudioSpeech接口启动录音。

  • 原型：

    UFUNCTION(BlueprintCallable, Category = "YoumeIMAPI Message")
static EYIMErrorcode StartAudioSpeech(bool translate, int64& requestID);

  • 参数：
    requestID：返回消息序列号。
    translate：是否进行语音转文字识别。

  • 返回值：
    EYIMErrorcode：错误码，详细描述见错误码定义。

停止录音并发送

可通过UYoumeIMAPI的StopAudioSpeech接口停止录音并发送，该接口只上传到服务器并异步返回音频文件的下载链接，下载链接指向的是AMR格式的音频文件，不会自动发送。 该接口对应StartAudioSpeech()。

  • 原型：

    UFUNCTION(BlueprintCallable, Category = "YoumeIMAPI Message")
static EYIMErrorcode StopAudioSpeech();

  • 返回值：
    EYIMErrorcode：错误码，详细描述见错误码定义。

  • 相关接口： 取消录音，调用该接口后，此次录音不会上传。

    //取消本次录音
UFUNCTION(BlueprintCallable, Category = "YoumeIMAPI Message")
static EYIMErrorcode CancleAudioMessage();

  • 回调接口：

    UFUNCTION(BlueprintNativeEvent, BlueprintCallable, Category = "YoumeIM Message")
void OnStopAudioSpeechStatus(const EYIMErrorcode& errorcode, UAudioSpeechInfo* audioSpeechInfo);

  • 参数：
    errorcode：错误码。
    audioSpeechInfo：录音信息。

  • 备注：
    UAudioSpeechInfo 类成员方法如下：
    GetRequestID()：消息ID。
    GetDownloadURL()：语音文件的下载地址。
    GetAudioTime()：录音时长，单位秒。
    GetFileSize()：文件大小，字节。
    GetLocalPath()：本地语音文件的路径。
    GetText()：语音识别结果，可能为空null or ""。

根据url下载录音文件

可通过UYoumeIMAPI的DownloadFile接口下载录音文件。

  • 原型：

    UFUNCTION(BlueprintCallable, Category = "YoumeIMAPI Message")
static EYIMErrorcode DownloadFile(const FString downloadURL, const FString savePath, EYIMFileType fileType);

  • 参数：
    downloadURL：语音文件的url地址，从OnStopAudioSpeechStatus回调获得。
    savePath：下载语音文件的本地存放地址,带文件名的全路径。

  • 返回值：
    EYIMErrorcode：错误码，详细描述见错误码定义。

  • 回调接口：

    UFUNCTION(BlueprintNativeEvent, BlueprintCallable, Category = "YoumeIM Download")
void OnDownloadByUrl(const EYIMErrorcode& errorcode, const FString& fromUrl, const FString& savePath, const int32& audioTime);
  • 回调参数：
    errorcode：错误码。
    strFromUrl：下载的语音文件url。
    strSavePath：本地存放地址。

消息屏蔽

屏蔽/解除屏蔽用户消息

可通过UYoumeIMAPI的BlockUser接口屏蔽/解除屏蔽用户消息，若屏蔽用户的消息，此屏蔽用户发送的私聊/频道消息都接收不到。

  • 原型：

    UFUNCTION(BlueprintCallable, Category = "YoumeIMAPI Message")
static EYIMErrorcode BlockUser(const FString userID, bool block);

  • 参数：
    userID：需屏蔽/解除屏蔽的用户ID。
    block：true-屏蔽 false-解除屏蔽。

  • 返回值：
    EYIMErrorcode：错误码，详细描述见错误码定义。

  • 回调接口：

    UFUNCTION(BlueprintNativeEvent, BlueprintCallable, Category = "YoumeIM Message")
void OnBlockUser(const EYIMErrorcode& errorcode, const FString& userID, const bool block);
  • 回调参数：
    errorcode：错误码。
    userID：用户ID。
    block：true-屏蔽 false-解除屏蔽。

解除所有已屏蔽用户

可通过UYoumeIMAPI的UnBlockAllUser接口解除所有已屏蔽消息的用户。

  • 原型：

    UFUNCTION(BlueprintCallable, Category = "YoumeIMAPI Message")
static EYIMErrorcode UnBlockAllUser();

  • 返回值：
    EYIMErrorcode：错误码，详细描述见错误码定义。

  • 回调接口：

    UFUNCTION(BlueprintNativeEvent, BlueprintCallable, Category = "YoumeIM Message")
void OnUnBlockAllUser(const EYIMErrorcode& errorcode);
  • 回调参数：
    errorcode：错误码。

获取被屏蔽消息用户

可通过UYoumeIMAPI的GetBlockUsers接口获取被屏蔽消息的用户。

  • 原型：

    UFUNCTION(BlueprintCallable, Category = "YoumeIMAPI Message")
static EYIMErrorcode GetBlockUsers();

  • 返回值：
    EYIMErrorcode：错误码，详细描述见错误码定义。

  • 回调接口：

    UFUNCTION(BlueprintNativeEvent, BlueprintCallable, Category = "YoumeIM Message")
void OnGetBlockUsers(const EYIMErrorcode& errorcode, const TArray<FString>& userList);
  • 回调参数：
    errorcode：错误码。
    userList：屏蔽用户ID列表。

消息功能设置

设置消息已读

可通过UYoumeIMAPI的SetMessageRead接口设置消息为已读。

  • 原型：

    UFUNCTION(BlueprintCallable, Category = "YoumeIMAPI Message")
static EYIMErrorcode SetMessageRead(int64 messageID, bool read);

  • 参数：
    messageID：消息ID。
    read：是否已读，true为已读，false为未读。

  • 返回值：
    EYIMErrorcode：错误码，详细描述见错误码定义。

批量设置消息已读

可通过UYoumeIMAPI的SetAllMessageRead接口批量设置消息为已读。

  • 原型：

    UFUNCTION(BlueprintCallable, Category = "YoumeIMAPI Message")
static EYIMErrorcode SetAllMessageRead(const FString userID, bool read);

  • 参数：
    userID：发消息的用户ID；用户ID为空字符串时，将登录用户的所有消息设置为已读/未读；用户ID不为空字符串时，将接收的由该用户ID发送的消息设置为已读/未读。
    read：是否已读，true为已读，false为未读。

  • 返回值：
    EYIMErrorcode：错误码，详细描述见错误码定义。

切换获取消息模式

可通过UYoumeIMAPI的SetReceiveMessageSwitch接口切换获取消息模式，在自动接收消息和手动接收消息间切换，默认是自动接收消息。

  • 原型：

      // 是否自动接收消息(true:自动接收(默认)   false:不自动接收消息，有新消息达到时，SDK会发出OnReceiveMessageNotify回调，调用方需要调用GetMessage获取新消息)
UFUNCTION(BlueprintCallable, Category = "YoumeIMAPI Message")
static EYIMErrorcode SetReceiveMessageSwitch(TArray<FString> vecRoomIDs, bool receive);

  • 参数：
    vecRoomIDs：频道ID的列表。
    receive：true为自动接收消息，false为手动接收消息，默认为true。

  • 返回值：
    EYIMErrorcode：错误码，详细描述见错误码定义。

手动获取消息

可通过UYoumeIMAPI的GetNewMessage接口手动获取消息。 在手动接收消息模式，需要调用该接口后才能收到 OnRecvMessage 通知。

  • 原型：

    UFUNCTION(BlueprintCallable, Category = "YoumeIMAPI Message")
static EYIMErrorcode GetNewMessage(TArray<FString> vecRoomIDs);

  • 参数：
    vecRoomIDs:频道ID。

  • 返回值：
    EYIMErrorcode：错误码，详细描述见错误码定义。

新消息通知

在手动接收消息模式，会通知有新消息。

  • 通知接口：

    UFUNCTION(BlueprintNativeEvent, BlueprintCallable, Category = "YoumeIM Message")
void OnReceiveMessageNotify(const EYIMChatType& chatType, const FString& targetID);
  • 参数：
    chatType：聊天类型，可以用于区分是频道聊天还是私聊。
    targetID：如果是频道聊天，该值为频道ID；私聊该值为空。

消息记录管理

设置是否保存频道聊天记录

可通过UYoumeIMAPI的SetRoomHistoryMessageSwitch接口设置是否保存频道聊天记录。（默认不保存）

  • 原型：

    UFUNCTION(BlueprintCallable, Category = "YoumeIMAPI Message")
static EYIMErrorcode SetRoomHistoryMessageSwitchMulti(TArray<FString> vecRoomIDs, bool save);

  • 参数：
    vecRoomIDs：频道ID列表。
    save：是否保存频道消息记录（默认不保存）true为保存，false为不保存，默认false。

  • 返回值：
    EYIMErrorcode：错误码，详细描述见错误码定义。

拉取频道最近聊天记录

可通过UYoumeIMAPI的QueryRoomHistoryMessageFromServer接口从服务器拉取频道最近的聊天历史记录。 这个功能默认不开启，需要的请联系我们修改服务器配置。联系我们，可以通过专属游密支持群或者技术支持的大群。

  • 原型：

    UFUNCTION(BlueprintCallable, Category = "YoumeIMAPI Message")
static EYIMErrorcode QueryRoomHistoryMessageFromServer(const FString roomID, int32 count, int32 direction);

  • 参数：
    roomID：频道id。
    count：消息数量(最大30条)。
    directon：历史消息排序方向 0：按时间戳升序 1：按时间戳逆序。

  • 返回值：
    EYIMErrorcode：错误码，详细描述见错误码定义。

  • 回调接口：

    UFUNCTION(BlueprintNativeEvent, BlueprintCallable, Category = "YoumeIM Message")
void OnQueryRoomHistoryMessageFromServer(const EYIMErrorcode& errorcode, const FString& roomID, const int32& remain, const TArray<UYIMMessage*>& messageList);

  • 回调参数：
    errorcode：错误码。
    roomID： 房间ID。
    remain： 剩余消息数量，该参数已弃用，目前返回值都是。
    messageList：消息列表，UYIMMessage消息基类详细，查看 接收消息备注。

  • 备注：该回调返回的消息记录会包括已屏蔽用户的消息。

本地历史记录管理

查询本地聊天历史记录

可通过UYoumeIMAPI的QueryHistoryMessage接口查询本地聊天历史记录。

  • 原型：

    UFUNCTION(BlueprintCallable, Category = "YoumeIMAPI Message")
static EYIMErrorcode QueryHistoryMessage(const FString targetID, EYIMChatType chatType, int64 startMessageID, int32 count, int32 direction);

  • 参数：
    targetID：用户ID或者频道ID。
    chatType：聊天类型，私聊／频道聊天。
    startMessageID：起始历史记录消息id（与requestid不同），为0表示首次查询，将倒序获取count条记录。
    count：最多获取多少条。
    direction：历史记录查询方向，startMessageID=0时,direction使用默认值0；startMessageID>0时，0表示查询比startMessageID小的消息，1表示查询比startMessageID大的消息。

  • 返回值：
    EYIMErrorcode：错误码，详细描述见错误码定义。

  • 相关函数： 对于房间本地记录，需要先设置自动保存房间消息。SetRoomHistoryMessageSwitch。

  • 回调接口：

    UFUNCTION(BlueprintNativeEvent, BlueprintCallable, Category = "YoumeIM Message")
void OnQueryHistoryMessage(const EYIMErrorcode& errorcode, const FString& targetID, const int32& remain, const TArray<UYIMMessage*>& messageList);
  • 回调参数：
    errorcode：错误码。
    targetID：用户ID/频道ID。
    remain：剩余历史消息条数。
    messageList：消息列表，IYIMMessage消息基类详细，查看 接收消息备注。
根据时间清理本地聊天历史记录

可通过UYoumeIMAPI的DeleteHistoryMessage接口清理本地聊天历史记录。建议定期清理本地历史记录。

  • 原型：

    UFUNCTION(BlueprintCallable, Category = "YoumeIMAPI Message")
static EYIMErrorcode DeleteHistoryMessage(EYIMChatType chatType, int64 time);

  • 参数：
    chatType：聊天类型，1私聊，2频道聊天。
    time：Unix timestamp,精确到秒，表示删除这个时间点之前的所有历史记录。

  • 返回值：
    EYIMErrorcode：错误码，详细描述见错误码定义。
根据ID清理本地聊天历史记录

可通过UYoumeIMAPI的DeleteHistoryMessageByID接口清理本地聊天历史记录。建议定期清理本地历史记录。

  • 原型：

    UFUNCTION(BlueprintCallable, Category = "YoumeIMAPI Message")
static EYIMErrorcode DeleteHistoryMessageByID(int64 messageID);

  • 参数：
    messageID：如果指定了大于0的值，将删除指定消息id的历史记录。

  • 返回值：
    EYIMErrorcode：错误码，详细描述见错误码定义。
根据用户ID或者频道ID清理指定的本地聊天历史记录

可通过UYoumeIMAPI的DeleteSpecifiedHistoryMessage接口清理本地聊天历史记录。 可以根据用户ID或者频道ID删除对应的本地聊天历史记录,保留消息ID白名单中的消息记录,白名单列表为空时删除与该用户ID或频道ID有关的所有本地聊天记录。

  • 原型：

    UFUNCTION(BlueprintCallable, Category = "YoumeIMAPI Message")
static EYIMErrorcode DeleteSpecifiedHistoryMessage(const FString targetID, EYIMChatType chatType, TArray<int64> excludeMesList);

  • 参数：
    targetID：用户ID或者频道ID。
    chatType：聊天类型，私聊/频道聊天，1是私聊，2是频道聊天。
    excludeMesList：消息ID白名单。

  • 返回值：
    EYIMErrorcode：错误码，详细描述见错误码定义。
根据用户ID或者频道ID清理本地聊天历史记录

可通过UYoumeIMAPI的DeleteHistoryMessage接口清理本地聊天历史记录。
可以根据用户ID或者频道ID删除以指定的起始消息ID开始的n条本地聊天历史记录，起始消息ID和消息数量使用默认值时则删除所有消息。

  • 原型：

    UFUNCTION(BlueprintCallable, Category = "YoumeIMAPI Message")
static EYIMErrorcode DeleteHistoryMessage(EYIMChatType chatType, int64 time);

  • 参数：
    targetID：用户ID或者频道ID。
    chatType：聊天类型，私聊/频道聊天，1是私聊，2是频道聊天。 startMessageID：起始消息ID(默认值0表示最近的一条消息)。
    count：消息数量(默认值0表示删除所有消息)。

  • 返回值：
    EYIMErrorcode：错误码，详细描述见错误码定义。
获取最近私聊联系人列表

可通过UYoumeIMAPI的GetRecentContacts接口获取最近私聊联系人列表，该接口是根据本地历史消息记录生成的最近联系人列表，按最后聊天时间倒序排列。该列表会受清理历史记录消息的接口影响。

  • 原型：

    UFUNCTION(BlueprintCallable, Category = "YoumeIMAPI")
static EYIMErrorcode GetRecentContacts();

  • 返回值：
    EYIMErrorcode：错误码，详细描述见错误码定义。

  • 回调接口：

    UFUNCTION(BlueprintNativeEvent, BlueprintCallable, Category = "YoumeIM Contact")
void OnGetRecentContacts(const EYIMErrorcode& errorcode, const TArray<UYIMContactsMessageInfo*>& contactList);

  • 回调参数：
    errorcode：错误码。
    contactList：最近联系人列表。

  • 备注：
    UYIMContactsMessageInfo类成员方法如下： GetContactID()：联系人ID。
    GetMessageType()：消息类型，枚举类型，
    MessageBodyType_Unknow = 0, //未知类型
    MessageBodyType_TXT = 1, //文本消息
    MessageBodyType_CustomMesssage = 2, //自定义消息
    MessageBodyType_Emoji = 3, //表情
    MessageBodyType_Image = 4, //图片
    MessageBodyType_Voice = 5, //语音
    MessageBodyType_Video = 6, //视频
    MessageBodyType_File = 7, //文件
    MessageBodyType_Gift = 8 //礼物
    GetMessageContent()：消息内容。
    GetCreateTime()：消息创建时间。
    GetNotReadMsgNum()：未读消息数量（此值有意义需结合SetMessageRead接口使用，可在收到消息后设置消息已读）。
    GetLocalPath()：本地路径（语音或文件消息）。
    GetExtra()：额外信息。

高级功能

文本翻译

可通过UYoumeIMAPI的TranslateText接口将文本翻译成指定语言的文本，异步返回结果通过IYoumeIMObserver的OnTranslateTextComplete接口返回。

  • 原型

    UFUNCTION(BlueprintCallable, Category = "YoumeIMAPI Message")
static EYIMErrorcode TranslateText(const FString text, EYIMLanguageCode destLangCode, EYIMLanguageCode srcLangCode, int32& requestID);

  • 参数：
    requestID：请求ID(SDK生成返回)。
    text：待翻译文本。
    destLangCode：目标语言编码。
    srcLangCode：原文本语言编码。

  • 返回值：
    EYIMErrorcode：错误码，详细描述见错误码定义。

  • 回调接口：

    UFUNCTION(BlueprintNativeEvent, BlueprintCallable, Category = "YoumeIM Message")
void OnTranslateTextComplete(const EYIMErrorcode& errorcode, const int32& requestID, const FString& text, const EYIMLanguageCode& srcLangCode, const EYIMLanguageCode& destLangCode);
  • 回调参数：
    errorcode：错误码，等于0才是操作成功。
    requestID：请求ID。
    text：翻译成指定语言的文本。
    srcLangCode：源语言编码。
    destLangCode：目标语言编码。

敏感词过滤

考虑到客户端可能需要传递一些自定义消息，关键字过滤方法就直接提供出来，客户端可以选择是否通过UYoumeIMAPI的FilterKeyword接口选择是否过滤关键字，并且可以根据匹配到的等级进行过滤。比如level返回的值为'2'表示广告，那么可以在发送时选择不发送，接收方可以选择不展示。

  • 原型：

    UFUNCTION(BlueprintCallable, Category = "YoumeIMAPI")
static FString FilterKeyword(const FString text, int level);

  • 参数：
    text：消息原文。
    level：匹配的策略词等级，默认为0，0表示正常，其余值是按需求可配。

  • 返回值：
    过滤关键字后的消息，敏感字会替换为"*"。

游戏切入后台与恢复

游戏切入后台通知

可通过UYoumeIMAPI的OnPause接口暂停游戏。 建议游戏切入后台时通知该接口，以便于得到更好重连效果。 调用OnPause(false),在游戏切入后台后,若IM是登录状态，依旧接收IM消息。 调用OnPause(true),游戏切入后台，即使IM是登录状态也不会接收IM消息；在游戏恢复运行时会主动拉取暂停期间未接收的消息，收到OnRecvMessage()回调。

  • 原型：

    UFUNCTION(BlueprintCallable, Category = "YoumeIMAPI")
static void OnPause(bool pauseReceiveMessage);
  • 参数：
    pauseReceiveMessage：是否暂停接收IM消息，true-暂停接收 false-不暂停接收。

游戏恢复运行通知

可通过UYoumeIMAPI的OnResume接口恢复游戏运行。 建议游戏从后台激活到前台时通知该接口，以便于得到更好重连效果。

  • 原型：

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

用户举报和禁言

用户举报

UYoumeIMAPI的Accusation接口提供举报功能，对[用户违规的发言内容]()进行举报，管理员在后台进行审核处理并将结果通知用户。

  • 原型

    UFUNCTION(BlueprintCallable, Category = "YoumeIMAPI Message")
static EYIMErrorcode Accusation(const FString userID, EYIMChatType source, int32 reason, const FString description, const FString nickName, const FString serverArea, const FString level, const FString vipLevel);

  • 参数：
    userID：被举报用户ID。
    source：来源（私聊/频道，1是私聊，2是频道聊天）。
    reason：原因，由用户自定义枚举。
    description：原因描述。
    extraParam：附加信息JSON格式 ({"nickname":"","server_area":"","level":"","vip_level":""}）。

  • 返回值：
    EYIMErrorcode：错误码，详细描述见错误码定义。

  • 举报处理结果通知： 当管理员对举报进行审核处理后，会将举报处理结果通知用户。

  • 原型：

    UFUNCTION(BlueprintNativeEvent, BlueprintCallable, Category = "YoumeIM Message")
void OnAccusationResultNotify(const EAccusationDealResult& result, const FString& userID, const int32& accusationTime);
  • 回调参数：
    result：处理结果，枚举类型，
    ACCUSATIONRESULT_IGNORE=0 // 忽略
    ACCUSATIONRESULT_WARNING=1 // 警告
    ACCUSATIONRESULT_FROBIDDEN_SPEAK=2 // 禁言
    userID：被举报用户ID。
    accusationTime：举报时间。

禁言查询

可通过UYoumeIMAPI的GetForbiddenSpeakInfo接口查询所在频道的禁言状态。

  • 原型：

    UFUNCTION(BlueprintCallable, Category = "YoumeIMAPI Message")
static EYIMErrorcode GetForbiddenSpeakInfo();

  • 返回值：
    EYIMErrorcode：错误码，详细描述见错误码定义。

  • 回调接口：

    UFUNCTION(BlueprintNativeEvent, BlueprintCallable, Category = "YoumeIM Message")
void OnGetForbiddenSpeakInfo(const EYIMErrorcode& errorcode, const TArray<UYIMForbidSpeakInfo*>& vecForbiddenSpeakInfos);

  • 回调参数：
    errorcode：错误码。
    vecForbiddenSpeakInfos：禁言状态列表,每一个代表一个频道的禁言状态。

  • 备注：
    UYIMForbidSpeakInfo 类成员方法如下：
    GetChannelID()：频道ID。
    GetIsForbidRoom()：此频道是否被禁言，true-被禁言，false-未被禁言。
    GetReasonType()：禁言原因类型，0-未知，1-发广告，2-侮辱，3-政治敏感，4-恐怖主义，5-反动，6-色情，7-其它。
    GetEndTime()：若被禁言，禁言结束时间。

公告管理

基本流程：申请开通公告功能->后台添加新公告然后设置公告发送时间,公告消息类型,发送时间,接收公告的频道等->(客户端流程) 设置对应监听-> 调用对应接口->回调接收。

公告功能简述

1.公告发送由后台配置，如类型、周期、发送时间、内容、链接、目标频道、次数、起始结束时间等。

2.公告三种类型：跑马灯，聊天框，置顶公告： (1) 跑马灯，聊天框公告可设置发送时间，次数和间隔（从指定时间点开始隔固定间隔时间发送多次，界面展示及显示时长由客户端决定）。 (2) 置顶公告需设置开始和结束时间（该段时间内展示）。

3.三种公告均有一次性、周期性两种循环属性： 一次性公告，到达指定时间点，发送该条公告。 周期性公告，跟一次性公告发送规则一致，但是可以设置发送周期（在每周哪几天的指定时间发送）。

4.跑马灯与聊天框公告只有发送时间点在线的用户才能收到该公告，显示规则由客户端自己决定，两者区别主要是界面显示的区分。

5.置顶公告有显示起始和结束时间，表示该时段内显示，公告发送时间点在线的用户会收到该公告，公告发送时间点未在线用户，在公告显示时段登录，登录后可通过查询公告接口查到该公告。

6.公告撤销 仅针对置顶公告，公告显示时段撤销公告，客户端会收到公告撤销通知，界面进行更新。

接收公告

管理员在后台发布公告，当到达指定时间会收到该公告，界面根据不同类型的公告进行展示。

  • 原型：

    UFUNCTION(BlueprintNativeEvent, BlueprintCallable, Category = "YoumeIM Notice")
void OnRecvNotice(UYIMNotice* notice);

  • 参数：
    notice：公告信息。

  • 备注：
    YIMNotice类成员方法如下： GetNoticeID()：公告ID，unsigned long long型。
    GetNoticeType()：公告类型，1-跑马灯公告 2-聊天框公告 3-置顶公告。
    GetChannelID()：发布公告的频道ID。
    GetContent()：公告内容。
    GetLinkText()：公告链接关键字。
    GetLinkAddr()：公告链接地址。
    GetBeginTime()：公告开始时间。
    GetEndTime()：公告结束时间。

撤销公告

对于某些类型的公告（如置顶公告），需要在界面展示一段时间，如果管理员在该时间段执行撤销该公告，会收到撤销公告通知，界面进行相应更新。

  • 原型：

    UFUNCTION(BlueprintNativeEvent, BlueprintCallable, Category = "YoumeIM Notice")
void OnCancelNotice(const int64& noticeID, const FString& channelID);
  • 参数：
    noticeID：公告ID。
    channelID：发布公告的频道ID。

查询公告

公告在配置的时间点下发到客户端，对于某些类型的公告（如置顶公告）需要在某个时间段显示在，如果用户在公告下发时间点未在线，而在公告展示时间段内登录，应用可根据自己的需要决定是否展示该公告，可通过UYoumeIMAPI的QueryNotice接口查询公告，结果通过上面的OnRecvNotice异步回调返回。

  • 原型：

    UFUNCTION(BlueprintCallable, Category = "YoumeIMAPI")
static EYIMErrorcode QueryNotice();
  • 返回值：
    EYIMErrorcode：错误码，详细描述见错误码定义。

地理位置

获取自己当前的地理位置

可通过UYoumeIMAPI的GetCurrentLocation接口请求获取自己当前地理位置。异步返回结果通过IYoumeIMObserver的OnUpdateLocation接口返回。

  • 原型：

    UFUNCTION(BlueprintCallable, Category = "YoumeIMAPI Location")
static EYIMErrorcode GetCurrentLocation();

  • 返回值：
    EYIMErrorcode：错误码，详细描述见错误码定义。

  • 回调接口：

    UFUNCTION(BlueprintNativeEvent, BlueprintCallable, Category = "YoumeIM Location")
void OnUpdateLocation(const EYIMErrorcode& errorcode, UGeographyLocation* location);

  • 回调参数：
    errorcode：等于0才是操作成功。
    location：当前地理位置及行政区划信息。

  • 备注：
    UGeographyLocation类成员方法如下：
    GetDistrictCode()：unsigned int类型，地理区域编码，可根据此参数组合附近频道id。
    GetCountry()：国家。
    GetProvince()：省份。
    GetCity()：城市。
    GetDistrictCounty()：区县。
    GetStreet()：街道。（目前只精确到区县，街道为保留字段）
    GetLongitude()：double类型，经度。
    GetLatitude()：double类型，纬度。

获取附近的人

可通过UYoumeIMAPI的GetNearbyObjects接口获取自己附近的人，若需要此功能，请联系我们开启LBS服务。若已开启服务，此功能生效的前提是自己和附近的人都获取了自己的地理位置，即调用了IM的获取当前地理位置接口。异步返回结果通过IYoumeIMObserver的OnGetNearbyObjects接口返回。

  • 原型：

    UFUNCTION(BlueprintCallable, Category = "YoumeIMAPI Location")
static EYIMErrorcode GetNearbyObjects(int32 count, const FString serverAreaID, EDistrictLevel districtlevel, bool resetStartDistance);

  • 参数：
    count：获取数量（一次最大200个）。
    serverAreaID：区服ID（对应设置用户信息中的区服，如果只需要获得本服务器的，要填；否则填""）。
    districtlevel：行政区划等级，枚举类型，
    DISTRICT_UNKNOW=0 //未知
    DISTRICT_COUNTRY=1 //国家
    DISTRICT_PROVINCE=2 //省份
    DISTRICT_CITY=3 //城市
    DISTRICT_COUNTY=4 //区县
    DISTRICT_STREET=5 //街道
    resetStartDistance：是否重置查找起始距离,true-从距自己0米开始查找，false-从上次查找返回的最远用户开始查找。

  • 返回值：
    EYIMErrorcode：错误码，详细描述见错误码定义。

  • 回调接口：

    UFUNCTION(BlueprintNativeEvent, BlueprintCallable, Category = "YoumeIM Location")
void OnGetNearbyObjects(const EYIMErrorcode& errorcode, const TArray<URelativeLocation*>& neighbourList, const int32& startDistance, const int32& endDistance);

  • 回调参数：
    errorcode：等于0才是操作成功。
    neighbourList：附近的人地理位置信息列表。
    startDistance：查找起始距离。
    endDistance：查找终止距离。

  • 备注：
    URelativeLocation类成员方法如下：
    GetDistance()：与自己的距离。
    GetLongitude()：经度。
    GetLatitude()：纬度。
    GetUserID()：附近用户ID。
    GetCountry()：国家。
    GetProvince()：省份。
    GetCity()：城市。
    GetDistrictCounty()：区县。
    GetStreet()：街道。（目前只精确到区县，街道为保留字段）

地理位置更新

从资源和耗电方面的考虑，SDK不自动监听地理位置的变化，如果调用方有需要可调用UYoumeIMAPI的SetUpdateInterval接口设置更新时间间隔，SDK会按设定的时间间隔监听位置变化并通知上层。调用该接口之前，需要调用GetCurrentLocation成功获取自己的地理位置。（如果应用对地理位置变化关注度不大，最好不要设置自动更新）

  • 原型：

    UFUNCTION(BlueprintCallable, Category = "YoumeIMAPI Location")
static void SetUpdateInterval(int32 interval);
  • 参数：
    interval：时间间隔（单位：分钟）。

获取与指定用户距离

可调用UYoumeIMAPI的GetDistance接口获取与指定用户距离；获取与指定用户距离之前，需要调用GetCurrentLocation成功获取自己的地理位置，指定的用户也调用GetCurrentLocation成功获取其地理位置。若指定的用户未成功获取到其地理位置，会返回无效的距离。

  • 原型：

    UFUNCTION(BlueprintCallable, Category = "YoumeIMAPI Location")
static EYIMErrorcode GetDistance(const FString userID);

  • 参数：
    userID：用户ID。

  • 返回值：
    EYIMErrorcode：错误码，详细描述见错误码定义。

  • 回调接口：

    UFUNCTION(BlueprintNativeEvent, BlueprintCallable, Category = "YoumeIM Location")
void OnGetDistance(const EYIMErrorcode& errorcode, const FString& userID, const int32& distance);
  • 回调参数：
    errorcode：错误码。
    userID: 用户ID。
    distance: 距离（米）。

全球布点选择

必须在初始化之前调用， 根据游戏主要发行区域，选择合适的 IM 服务器区域。如果不调用该接口进行设置，默认的服务器区域是中国。

  • 原型：

    UFUNCTION(BlueprintCallable, Category = "YoumeIMAPI")
static void SetServerZone(EServerZone Zone);
  • 参数：
    zone：服务器区域，参考ServerZone枚举说明。

服务器部署地区定义

ServerZone.China = 0         // 中国
ServerZone.Singapore = 1     // 新加坡  
ServerZone.America = 2     // 美国
ServerZone.HongKong = 3        // 香港
ServerZone.Korea = 4           // 韩国
ServerZone.Australia = 5     // 澳洲
ServerZone.Deutschland = 6  // 德国
ServerZone.Brazil = 7       // 巴西
ServerZone.India = 8           // 印度
ServerZone.Japan = 9           // 日本
ServerZone.Ireland = 10    // 爱尔兰
ServerZone.ServerZone_Unknow = 9999

错误码定义

错误码 含义
Success = 0 成功
EngineNotInit = 1 IM SDK未初始化
NotLogin = 2 IM SDK未登录
ParamInvalid = 3 无效的参数
TimeOut = 4 超时
StatusError = 5 状态错误
SDKInvalid = 6 Appkey无效
AlreadyLogin = 7 已经登录
LoginInvalid = 1001 登录无效
ServerError = 8 服务器错误
NetError = 9 网络错误
LoginSessionError = 10 登录状态出错
NotStartUp = 11 SDK未启动
FileNotExist = 12 文件不存在
SendFileError = 13 文件发送出错
UploadFailed = 14 文件上传失败,上传失败 一般都是网络限制上传了
UsernamePasswordError = 15, 用户名密码错误
UserStatusError = 16, 用户状态为无效用户
MessageTooLong = 17, 消息太长
ReceiverTooLong = 18, 接收方ID过长（检查频道名）
InvalidChatType = 19, 无效聊天类型
InvalidReceiver = 20, 无效用户ID
UnknowError = 21, 未知错误
InvalidAppkey = 22, AppKey无效
ForbiddenSpeak = 23, 被禁止发言
CreateFileFailed = 24, 创建文件失败
UnsupportFormat = 25, 支持的文件格式
ReceiverEmpty = 26, 接收方为空
RoomIDTooLong = 27, 房间名太长
ContentInvalid = 28, 聊天内容严重非法
NoLocationAuthrize = 29, 未打开定位权限
UnknowLocation = 30, 未知位置
Unsupport = 31, 不支持该接口
NoAudioDevice = 32, 无音频设备
AudioDriver = 33, 音频驱动问题
DeviceStatusInvalid = 34, 设备状态错误
ResolveFileError = 35, 文件解析错误
ReadWriteFileError = 36, 文件读写错误
NoLangCode = 37, 语言编码错误
TranslateUnable = 38, 翻译接口不可用
SpeechAccentInvalid = 39, 语音识别方言无效
SpeechLanguageInvalid = 40, 语音识别语言无效
HasIllegalText = 41, 消息含非法字符
AdvertisementMessage = 42, 消息涉嫌广告
AlreadyBlock = 43, 用户已经被屏蔽
NotBlock = 44, 用户未被屏蔽
MessageBlocked = 45, 消息被屏蔽
LocationTimeout = 46, 定位超时
NotJoinRoom = 47, 未加入该房间
LoginTokenInvalid = 48, 登录token错误
CreateDirectoryFailed = 49, 创建目录失败
InitFailed = 50, 初始化失败
Disconnect = 51, 与服务器断开
TheSameParam = 52, 设置参数相同
QueryUserInfoFail = 53, 查询用户信息失败
SetUserInfoFail = 54, 设置用户信息失败
UpdateUserOnlineStateFail = 55, 更新用户在线状态失败
NickNameTooLong = 56, 昵称太长(> 64 bytes)
SignatureTooLong = 57, 个性签名太长(> 120 bytes)
NeedFriendVerify = 58, 要好友验证信息
BeRefuse = 59, 添加好友被拒绝
HasNotRegisterUserInfo = 60, 未注册用户信息
AlreadyFriend = 61, 已经是好友
NotFriend = 62, 非好友
NotBlack = 63, 不在黑名单中
PhotoUrlTooLong = 64, 头像url过长(>500 bytes)
PhotoSizeTooLarge = 65, 头像太大（>100 kb）
ChannelMemberOverflow = 66, 达到频道人数上限
ALREADYFRIENDS = 1000, 服务器错误
LoginInvalid = 1001, 服务器错误登录无效
PTT_Start = 2000, 开始录音
PTT_Fail = 2001, 录音失败
PTT_DownloadFail = 2002, 语音消息文件下载失败
PTT_GetUploadTokenFail = 2003, 获取语音消息Token失败
PTT_UploadFail = 2004, 语音消息文件上传失败
PTT_NotSpeech = 2005, 没有录音内容
PTT_DeviceStatusError = 2006, 语音设备状态错误
PTT_IsSpeeching = 2007, 录音中
PTT_FileNotExist = 2008, 文件不存在
PTT_ReachMaxDuration = 2009, 达到语音最大时长限制
PTT_SpeechTooShort = 2010, 录音时间太短
PTT_StartAudioRecordFailed = 2011, 启动录音失败
PTT_SpeechTimeout = 2012, 音频输入超时
PTT_IsPlaying = 2013, 正在播放
PTT_NotStartPlay = 2014, 未开始播放
PTT_CancelPlay = 2015, 主动取消播放
PTT_NotStartRecord = 2016, 未开始语音
PTT_NotInit = 2017, 未初始化
PTT_InitFailed = 2018, 初始化失败
PTT_Authorize = 2019, 录音权限
PTT_StartRecordFailed = 2020, 启动录音失败
PTT_StopRecordFailed = 2021, 停止录音失败
PTT_UnsupprtFormat = 2022, 不支持的格式
PTT_ResolveFileError = 2023, 解析文件错误
PTT_ReadWriteFileError = 2024, 读写文件错误
PTT_ConvertFileFailed = 2025, 文件转换失败
PTT_NoAudioDevice = 2026, 无音频设备
PTT_NoDriver = 2027, 驱动问题
PTT_StartPlayFailed = 2028, 启动播放失败
PTT_StopPlayFailed = 2029, 停止播放失败
PTT_RecognizeFailed = 2030, 识别失败
Fail = 10000 语音服务启动失败