文档中心

云手机

客户端 SDK 参考

Message Channel SDK

Message Channel SDK 为部署在火山引擎云手机环境的云手机与客户端 APP 提供消息传输的系统解决方案，可以支持免登、支付和客户端与云机应用的互动等场景。Message Channel SDK 的具体功能如下:

客户端 APP 与云机实例之间收发消息（客户端 SDK 的使用方法，参考 Android SDK 接口说明)

本文档描述了 Message Channel SDK 的使用说明，方便您快速接入。

发版说明

2024/09/25：

Message Channel SDK V1.1.1 版本的发布说明如下：

更新 SDK 接入地址，接入时在应用模块的 build.gradle 文件中的 dependencies 中添加以下依赖：

2023/02/28

Message Channel SDK V1.0.9 版本的发布说明如下：

更新 SDK 接入地址，接入时在应用模块的 build.gradle 文件中的 dependencies 中添加以下依赖：

2022/11/10

Message Channel SDK V1.0.7 版本的发布说明如下：

新增获取客户端在启动云手机时发送到云机的通用信息数据接口（requestGeneralData）。

2022/10/12

Message Channel SDK V1.0.6 版本的发布说明如下：

云机应用发送消息给客户端接口新增 timeout 参数，支持指定消息发送超时时长。

2022/09/08

Message Channel SDK V1.0.5 版本的发布说明如下：

支持多用户场景，云手机客户端可以和多个云机实例之间传输自定义消息。云手机客户端 SDK 的 sendMessage 接口新增 channelUid 可选参数，用于指定云机应用初始化 veMessageChannelClient 时填入的用户 ID。

云手机客户端和云机应用之间的消息通道连接行为变更。当客户端调用 stop 接口停止拉流、客户端和云手机应用之间已建立的消息通道连接断开；当客户端调用 start 接口重新启动云手机后，veMessageChannelClient 会主动恢复客户端和云手机应用之间的消息通道连接。

接口说明

初始化

描述：初始化，创建与服务以及云手机客户端的连接。仅主进程才可执行初始化操作。方法如下：

参考示例：

参数说明：

参数名	类型	是否必选	描述
context	Context	是	上下文信息，建议填写 Application Context
userId	String	是	（一般情况下，建议直接使用应用包名）在多用户场景时，用于指定用户的唯一标识
accessKey	String	是	在建立连接时用于鉴权，建议采用以下鉴权方式： String accessKey = DigestUtils.md5Hex(PackageName); （注：需注意包名的大小写一致，例如，应用包名为：com.Android.Demo，则对应的 accessKey 为 String accessKey = DigestUtils.md5Hex("com.Android.Demo");
handler	IMessageHandler	是	初始化结果回调，参考以下 IMessageHandler 回调说明

IMessageHandler 回调说明：

方法	返回值	参数说明	描述
onInitSuccess()	void	空	初始化成功回调
onFailed()	void	errorCode: Integer，取值参考错误码及说明 message: String，错误描述	运行过程中发生的失败回调
onSendResult()	void	resultCode: Integer，取值参考错误码及说明 messageId: String，消息 ID	消息发送结果回调
onReceivedMessage()	void	userId: String，消息发送端的 ID msg: VeMessage，消息类型，参考类型说明	收到对端发送过来的消息
onConnectionStateChanged()	void	state: Integer，通道连接状态码，参考状态说明	通道连接状态变化监听

云机实例发送消息给客户端

描述：云机实例发送文本消息给云手机客户端 APP。方法如下：

参考示例：

参数说明：

参数名	类型	是否必选	描述
message	String	是	发送的消息内容
needsAck	Boolean	是	是否需要回执： true：需要回执，客户端收到消息后会回复ack，见 IMessageHandler.onReceiveAck(); false：不需要回执
timeout	Long	是	消息发送超时时长，单位 ms（需要大于0；当超过 timeout 指定的时间客户端仍然未收到消息，通过 IMessageHandler#onSentResult 返回消息发送失败信息）

云机实例接收客户端的消息

详细信息，参考初始化章节中的 IMessageHandler.onReceivedMessage() 说明。

请求通用信息数据

描述：获取客户端在启动云手机时发送到云机的通用信息数据（即通过启动云手机时通过 extra 参数发送的数据）。方法如下：

参数说明：

参数名	类型	是否必选	描述
cmd	String	是	命令，参考以下 Constant 说明
handler	IGeneralDataHandler	是	通用信息数据请求结果回调，参考以下 IGeneralDataHandler 回调说明

参考示例：

Constant 说明：

IGeneralDataHandler 回调说明：

检验 SDK 是否运行在云机环境

描述：判断 SDK 是否在火山云机环境运行。方法如下：

参考示例：

返回值：

true：SDK 在云机环境运行

false：SDK 未在云机环境运行

类型说明

VeMessage

字段	类型	描述
messageId	String	消息 ID
text	String	消息体，整包大小为 60KB
timeMillis	Long	时间戳，精确到毫秒

状态说明

消息通道连接状态说明如下：

状态码	状态说明	描述
1	CONNECTION_STATE_CONNECTED	已连接，初始化完成、与客户端之间通道连接成功时触发
2	CONNECTION_STATE_DISCONNECTED	已断连，与客户端之间通道连接断开时触发
3	CONNECTION_STATE_STOP	通道停止工作（可二次启动通道）

错误码及说明

错误码	错误信息	描述
1	ERROR_CODE_CONNECT_FAILED	与服务连接失败
2	ERROR_CODE_DISCONNECT	与服务断连
3	ERROR_CODE_SEND_FAILED	消息发送失败（Not connected）消息通道未连（Bad timeout）消息发送超时时长设置错误，timeout 的值必须大于0
4	ERROR_CODE_NOT_CLOUD_RUNTIME	SDK 未在云机环境运行
5	ERROR_CODE_CONNECT_VERIFY_FAILED	鉴权失败
6	ERROR_CODE_MESSAGE_FORMAT	消息格式错误

集成准备

注意：Message Channel SDK 目前不支持本地调试，您可以参考demo自行搭建测试环境

环境要求

支持 Android 4.1（API 级别 16）及以上系统。

快速接入

添加 Maven 仓库地址

确保 Project 根目录下的 build.gradle 文件中的 repositories 中配置了 maven 仓库地址，参考以下示例：

添加 SDK 依赖

在应用模块的 build.gradle 文件中的 dependencies 中添加 SDK 依赖，参考以下示例：

需要设置 Java 版本到1.8，参考以下示例：

权限声明

根据实际场景在 AndroidManifest.xml 文件中声明 SDK 需要的权限，参考以下示例：

说明：

存储写入权限需动态申请。参考：https://developer.android.com/training/permissions/requesting

如果 App 指向 Android 10 以上 (targetSdkVersion >= 29)，而且还未适配 “Scoped Storage”。请将 AndroidManifest.xml 中的 requestLegacyExternalStorage 设置为 true。参考: https://developer.android.com/training/data-storage/use-cases#opt-out-scoped-storage

最近更新时间：2026.06.17 17:55:41

这个页面对您有帮助吗？

有用

无用