Message Channel SDK 为部署在火山引擎云手机环境的云手机与客户端 APP 提供消息传输的系统解决方案，可以支持免登、支付和客户端与云机应用的互动等场景。Message Channel SDK 的具体功能如下: * 客户端 APP 与云机实例之间收发消息（客户端 SDK 的使用方法，参考 [Android SDK 接口说明](https://www.volcengine.com/docs/6394/75742)) 本文档描述了 Message Channel SDK 的使用说明，方便您快速接入。 ## 发版说明 ### 2024/09/25： Message Channel SDK V1.1.1 版本的发布说明如下： * 更新 SDK 接入地址，接入时在应用模块的 `build.gradle` 文件中的 `dependencies` 中添加以下依赖： ```java implementation 'com.bytedance.message:VePhoneMsgChannelClient:1.1.1' ``` ### 2023/02/28 Message Channel SDK V1.0.9 版本的发布说明如下： * 更新 SDK 接入地址，接入时在应用模块的 `build.gradle` 文件中的 `dependencies` 中添加以下依赖： ```java implementation 'com.bytedance.message:VePhoneMsgChannelClient:1.0.9' ``` ### 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 会主动恢复客户端和云手机应用之间的消息通道连接。 ## 接口说明 ### 初始化 **描述：** 初始化，创建与服务以及云手机客户端的连接。仅主进程才可执行初始化操作。方法如下： ```java void init(Context context, String userId, String accessKey, IMessageHandler handler) ``` **参考示例：** ```java VeMessageChannelClient.getnstance().init(context, userId, accessKey, handler) ``` **参数说明：** |参数名 |类型 |是否必选 |描述 | |---|---|---|---| |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，取值参考 [错误码及说明](https://www.volcengine.com/docs/6394/95333#.6ZSZ6K-v56CB5Y-K6K-05piO)

* message: String，错误描述 |运行过程中发生的失败回调 | |onSendResult() |void |* resultCode: Integer，取值参考 [错误码及说明](https://www.volcengine.com/docs/6394/95333#.6ZSZ6K-v56CB5Y-K6K-05piO)

* messageId: String，消息 ID |消息发送结果回调 | |onReceivedMessage() |void |* userId: String，消息发送端的 ID

* msg: VeMessage，消息类型，参考 [类型说明](https://www.volcengine.com/docs/6394/95333#.57G75Z6L6K-05piO) |收到对端发送过来的消息 | |onConnectionStateChanged() |void |state: Integer，通道连接状态码，参考 [状态说明](https://www.volcengine.com/docs/6394/95333#.54q25oCB6K-05piO) |通道连接状态变化监听 | ### 云机实例发送消息给客户端 **描述：** 云机实例发送文本消息给云手机客户端 APP。方法如下： ```java VeMessage sendMessageToClient(String message, boolean needsAck, long timeout) ``` **参考示例：** ```java VeMessageChannelClient.getInstance().sendMessageToClient("message", true, 6000); ``` **参数说明：** |**参数名** |**类型** |**是否必选** |**描述** | |---|---|---|---| |message |String |是 |发送的消息内容 | |needsAck |Boolean |是 |是否需要回执：

* true：需要回执，客户端收到消息后会回复ack，见 `IMessageHandler.onReceiveAck();`

* false：不需要回执 | |timeout |Long |是 |消息发送超时时长，单位 ms（需要大于0；当超过 timeout 指定的时间客户端仍然未收到消息，通过 IMessageHandler#onSentResult 返回消息发送失败信息） | ### 云机实例接收客户端的消息详细信息，参考 [初始化章节](https://www.volcengine.com/docs/6394/95333#.5Yid5aeL5YyW) 中的 `IMessageHandler.onReceivedMessage()` 说明。 ### 请求通用信息数据 **描述：** 获取客户端在启动云手机时发送到云机的通用信息数据（即通过启动云手机时通过 `extra` 参数发送的数据）。方法如下： ```java VeMessageChannelClient.getInstance().requestGeneralData(String cmd, IGeneralDataHandler handler) ``` **参数说明：** |参数名 |类型 |是否必选 |描述 | |---|---|---|---| |cmd |String |是 |命令，参考以下 **Constant 说明** | |handler |IGeneralDataHandler |是 |通用信息数据请求结果回调，参考以下 **IGeneralDataHandler 回调说明** | **参考示例：** ```java /** * 请求通用信息数据 * * @param cmd value of {@link Constant#GENERAL_CMD_GET_EXTRA} */ public void requestGeneralData(String cmd, IGeneralDataHandler handler) { if (mMessageChannelDelegate == null || handler == null) { return; } if (TextUtils.isEmpty(cmd)) { handler.onGeneralDataBack("Bad cmd !"); return; } mMessageChannelDelegate.sendCommandToSystem(new VeCmd(cmd)); } ``` **Constant 说明：** ```java /** * Request general data cmd: get extra */ public static final String GENERAL_CMD_GET_EXTRA = "get_extra"; ``` **IGeneralDataHandler 回调说明：** ```java public interface IGeneralDataHandler { /** * 通过此接口返回由 {@link VeMessageChannelClient#requestGeneralData(String, IGeneralDataHandler)}请求的数据 * * @param data 异步返回请求的通用数据 */ void onGeneralDataBack(String data); } ``` ### 检验 SDK 是否运行在云机环境 **描述：** 判断 SDK 是否在火山云机环境运行。方法如下： ```java isCloudRuntime() ``` **参考示例：** ```java VeMessageChannelClient.getInstance().isCloudRuntime() ``` **返回值：** * 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 仓库地址，参考以下示例： ```java buildscript { repositories { maven { url 'https://artifact.bytedance.com/repository/Volcengine/' } } } allprojects { repositories { maven { url 'https://artifact.bytedance.com/repository/Volcengine/' } } } ``` **添加 SDK 依赖** 在应用模块的 `build.gradle` 文件中的 `dependencies` 中添加 SDK 依赖，参考以下示例： ```java implementation 'com.bytedance.message:VePhoneMsgChannelClient:1.1.1' ``` 需要设置 Java 版本到1.8，参考以下示例： ```java android { // ... compileOptions { sourceCompatibility JavaVersion.VERSION_1_8 targetCompatibility JavaVersion.VERSION_1_8 } } ``` **权限声明** 根据实际场景在 `AndroidManifest.xml` 文件中声明 SDK 需要的权限，参考以下示例： ```java //读写存储

``` > 说明： > 1. 存储写入权限需动态申请。参考：[https://developer.android.com/training/permissions/requesting](https://developer.android.com/training/permissions/requesting) > 2. 如果 App 指向 Android 10 以上 (targetSdkVersion \>= 29)，而且还未适配 “Scoped Storage”。请将 `AndroidManifest.xml` 中的 `requestLegacyExternalStorage` 设置为 `true`。参考: [https://developer.android.com/training/data-storage/use-cases#opt-out-scoped-storage](https://developer.android.com/training/data-storage/use-cases#opt-out-scoped-storage) > ```java ```