介绍

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

集成云游戏手游 Message Channel SDK 的宿主 APP 需为 Android 环境运行的程序（有关云游戏客户端 veGameSDK 的使用方法，参考 Android SDK 接口说明。

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

发版说明

2024/8/28

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

• 修复部分已知问题。

2023/12/05

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

• 新增收发二进制数据相关接口。详细信息，参考 云端游戏发送二进制数据给客户端。

2023/02/28

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

• 文件传输接口中，新增 options 参数，支持收发文件时传输自定义参数。

2023/01/05

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

• 新增文件传输相关接口说明。详细信息，参考 文件传输接口。

2022/11/24

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

• 去除 gson 依赖，发布 lite 版本。详细信息，参考 快速接入。

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 接口新增 destChannelUid 可选参数，用于指定云端游戏初始化 veMessageChannelClient 时填入的用户 ID。
• 新增了客户端和云端游戏之间的消息通道连接行为变更。当客户端调用 stop 接口停止拉流、客户端和云端游戏之间已建立的消息通道连接断开；当客户端调用 start 接口重新启动游戏后，veMessageChannelClient 会主动恢复客户端和云端游戏之间的消息通道连接。

快速接入

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

环境要求

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

接入 SDK

添加 Maven 仓库地址

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

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 依赖，参考以下示例：

implementation 'com.bytedance.message:VeMsgChannelClient:1.0.9.2'

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

android {
    // ...
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
}

权限声明

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

//读写存储
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />

说明：

1. 存储写入权限需动态申请。参考：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

<manifest>
<application android:requestLegacyExternalStorage="true">
</application>
</manifest>

接口说明

初始化

描述： 初始化，创建与服务的连接。方法如下：

void init(Context context, String userId, String accessKey, IMessageHandler handler)

参考示例：

VeMessageChannelClient.getInstance().init(context, userId, accessKey, handler)

参数说明：

IMessageHandler 回调说明

云端游戏发送文本消息给客户端

描述： 云端游戏发送文本消息给云游戏客户端 APP。方法如下：

VeMessage sendMessageToClient(String message, boolean needsAck, long timeout)

参考示例：

VeMessageChannelClient.getInstance().sendMessageToClient("message", true, 6000);

参数说明：

云端游戏发送二进制数据给客户端

描述： 云端游戏发送二进制数据给云游戏客户端APP。方法如下：

VeBinaryMessage sendBinaryMessageToClient(byte[] payload, boolean needAck, `long timeout`)

参考示例：

VeMessageChannelClient.getInstance().sendBinaryMessageToClient(payload, true, 6000);

参数说明：

云端游戏接收客户端文本的消息

详情见 初始化 章节中的 IMessageHandler.onReceivedMessage()。

云端游戏接收客户端的二进制消息

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

请求通用信息数据

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

VeMessageChannelClient.getInstance().requestGeneralData(String cmd, IGeneralDataHandler handler)

参数说明：

参考示例：

/**
 * 请求通用信息数据
 *
 * @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 说明：

/**
 * Request general data cmd: get extra
 */
public static final String GENERAL_CMD_GET_EXTRA = "get_extra";

IGeneralDataHandler 回调说明：

public interface IGeneralDataHandler {

    /**
     * 通过此接口返回由 {@link VeMessageChannelClient#requestGeneralData(String, IGeneralDataHandler)}请求的数据
     * 
     * @param result 结果-Error code
     *               1: <li>{@link #ERROR_CODE_SUCCESS}<li/> 
     *               2: <li>{@link #ERROR_CODE_FAILED_INVALID_CMD}<li/>
     *               3: <li>{@link #ERROR_CODE_FAILED_NO_CONNECTION}<li/>
     * @param data 异步返回请求的通用数据
     */
    void onGeneralDataBack((int result,String data);

}

文件传输接口

描述：云游戏客户端与云端游戏之间收发文件。方法如下：

/**
 * 云端游戏向客户端发送大文件
 *
 * @param filePath 本地文件绝对路径
  * @param options 自定义参数，由云端 App 发送到客户端，可以为空
 * @return 0-成功，1-失败，2-未连接
 * @apiNote veGameSDK Version >= 1.21.0
 *
 */
public int sendFile(String filePath, Map<String, String> options) {
    return transFileCmd(filePath, Constant.GENERAL_CMD_SEND_FILE);
}

/**
  * 停止发送中的文件
  *
  *  @param  filePath 本地文件绝对路径
  *  @return  0-成功，1-失败，2-未连接
  *  @apiNote  veGameSDK Version >= 1.19.0
  *
  */
public int cancelSendFile(String filePath) {
    return transFileCmd(filePath, Constant.GENERAL_CMD_CANCEL_FILE);
}

/**
  * 设置文件发送/接收结果监听
  *
  *  @param  listener 接收大文件传输结果回调
  */
public void setFileTransportResultListener(IFileTransportResultListener listener) {
    if (mMessageChannelDelegate != null) {
        mMessageChannelDelegate.setFileTransportResultListener(listener);
    }
}

IFileTransportResultListener 回调说明

public interface IFileTransportResultListener {
    
    /** 发送/接收文件 成功 */
    int RESULT_SUCCESS = 0;
    
    /** 发送/接收文件 失败 */
    int RESULT_FAILED = 1;
    
    /** 发送/接收文件 取消 */
    int RESULT_CANCEL = 2;

    /** 表示本次文件发送由云端游戏发起 */
    int FLAG_SENDER_CLOUD_APP = 5;
    
    /** 表示本次文件发送由客户端发起 */
    int FLAG_SENDER_VE_SDK = 6;

    
    /**
     * 云端游戏发起，调用大文件发送接口{@link VeMessageChannelClient#sendFile(String)}结果回调
     *
     * @param result 结果- code
     *               <li>{@link #RESULT_SUCCESS}<li/>
     *               <li>{@link #RESULT_FAILED}<li/>
     *               <li>{@link #RESULT_CANCEL}<li/>
     * @param file 文件绝对路径，客户端保存文件的绝对路径
     * @param md5 文件md5校验，{@link #RESULT_FAILED}可能为空
     * @param options 自定义参数，由云端游戏发送到客户端
     *
     */
    void onSendFileResult(int result, String file, String md5, Map<String, String> options);

    
    /**
     * 客户端发起，客户端发送大文件至云端游戏结果回调
     *
     * @param result 结果- code
     *               <li>{@link #RESULT_SUCCESS}<li/>
     *               <li>{@link #RESULT_FAILED}<li/>
     *               <li>{@link #RESULT_CANCEL}<li/>
     * @param file 文件绝对路径，云端游戏保存文件的绝对路径
     * @param md5 文件md5校验，{@link #RESULT_FAILED}可能为空
     * @param options 自定义参数，由客户端发送到云端游戏
     */
    void onReceiveFileResult(int result, String file, String md5, Map<String, String> options);

}

参考示例：

VeMessageChannelClient.getInstance().sendFile(filePath)

VeMessageChannelClient.getInstance().cancelSendFile(filePath)

VeMessageChannelClient.getInstance().setFileTransportResultListener(new IFileTransportResultListener() {
    @Override
    public void onSendFileResult(int result, String file, String md5, Map<String, String> options) {
        // 由云端游戏发起，大文件发送，结果回调
    }

    @Override
    public void onReceiveFileResult(int result, String file, String md5, Map<String, String> options) {
        // 由客户端发起，发送大文件至云端游戏结果回调
    }
});

检验 SDK 是否运行在云端游戏环境

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

isCloudRuntime()

参考示例：

VeMessageChannelClient.getInstance().isCloudRuntime()

返回值：

• true（SDK 在云端游戏环境运行）
• false（SDK 未在云端游戏环境运行）

类型说明

VeMessage

VeBinaryMessage

状态说明

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

错误码及说明