04/29/2024 11:54:53

扩展模块开发

一、插件开发说明

扩展模块用于封装无法复用现有 MSDK 接口的功能，比如渠道内置的游戏商城。业务所需功能，建议尽量先复用现有 MSDK 接口，便于游戏在不同渠道发行。在无法复用情况下，再选择走扩展模块实现。

1.1 扩展模块说明

扩展模块调用说明：扩展模块可以封装任何游戏需要的功能。游戏在使用扩展模块的功能时需要将渠道名称（channel）、方法名（extendMethodName）和方法参数列表（paramsJson, Json 格式）传入，MSDK Core 将根据渠道名称和方法名查找到对应方法，调用到 Extend 插件进行处理。

扩展模块方法运行线程：

调用线程：调用扩展模块中的方法时，将直接使用游戏调用的线程进行执行，不会做自动切换线程处理。如有在方法中进行耗时操作或者 UI 处理，需要先自主进行线程切换，然后再调用扩展模块方法
回调线程：方法回调时，考虑到回调中很可能存在 UI 操作，因此回调线程会默认切换到 UI 线程进行处理（UnrealEngine 将自动切换到Game Thread）

[info] 注意 扩展模块不支持方法重载，需要重新定义新的方法名

1.2 扩展模块返回说明

扩展模块调用结果数据，支持同步返回和异步回调两种方式。同步返回结果将以字符串类型返回，异步回调结果可以通过游戏预先设置的 Observer 返回。具体流程如下图所示：

同步返回，其结果数据将从 Extend 插件通过 MSDK Extend Core 透传给游戏，具体的填写规则可以自定义。比如，可以返回 true 或者 false，也可以返回 Json 字符串，如果游戏不关心这个同步调用结果，还可以直接返回空。

异步回调，在调用时就需要传入对应的 Observer，其结果数据也将通过该 Observer 对应回调到其处理函数中。

二、客户端插件开发

2.1 Android 平台

2.1.1 类规则说明

包名规则：固定为 com.tencent.gcloud.msdk.extend
类名规则：渠道 + Extend，如：GarenaExtend
必须实现一个 public CLASSNAME(String seqID) 构造函数。通常用于函数初始化
扩展模块不需要实现其他接口，但是 MSDK 对扩展模块的方法参数列表、返回值、访问修饰符作如下规定：
- 方法参数列表，有且仅有 String paramsJson, String seqID
  - paramsJson
    String 类型，JSON 格式，为功能所需的参数列表信息。比如 Garena 商城需要 region、roleId、serverId 参数，paramsJson 可以为 {"region":"TW","roleId":234234,"serverId":4}。在方法实现中，需要解析 paramsJson 来获取方法具体所需的参数信息。
  - seqID
    String 类型，MSDK 函数调用序列 ID，用于标记是哪一次函数调用，建议日志中添加对应的标记方便定位问题
- 返回值，必须为 String 类型，该值用于给游戏同步返回方法的调用结果
- 访问修饰符，必须为 public，使得方法对外暴露

2.1.2 回调字段说明

回调函数说明，可参考客户端插件开发规则

observerID 回调函数 ID
- MSDKObserverID.MSDK_EXTEND_OBSERVER_RET ，Extend 模块统一的 observerID
ret 返回结构，统一为 MSDKExtendRet
- 回调结果中除了必要的成功/失败信息外，还需要设置 channel 和 extendMethodName，用于回调时游戏根据 channel 和 extendMethodName 进行进一步处理。其中，channel 为渠道名（比如 Garena），extendMethodName 为该方法的函数名（比如 openMS）
- 如果需要返回复杂的回调数据（比如特殊的好友列表信息），可以以 Json 格式赋值到 ret.extraJson 中
methodNameID MSDK 定义的函数 ID，用于回调方法定义
- MSDKMethodNameID.MSDK_EXTEND 为 Extend 模块统一的方法 ID

2.1.3 框架示例

package com.tencent.gcloud.msdk.extend;

public class GarenaExtend {

  public GarenaExtend(String seqID) {
      MSDKLog.d("[ " + seqID + "] Garena Extend initialize");
      // TODO 初始化 Garena 环境
      ...
  }

  public String openMS(String paramsJson, final String seqID) {
      MSDKLog.d("[ " + seqID + "] openMS paramsJson: " + paramsJson);
      // 回调时的 extend 方法名
      final String extendMethodName = "openMS";
      // 根据 paramsJson 解析具体的参数
      final String region = IT.getJsonString(paramsJson, "region");
      MSDKLog.d("[ " + seqID + "] openMS region: " + region);
      // 调用渠道方法
      ...

      // 返回方法调用成功
      IT.onPluginRetCallback(MSDK_EXTEND_OBSERVER_RET, new MSDKExtendRet(MSDK_EXTEND, MSDKErrorCode.SUCCESS, GarenaConst.Channel.CHANNEL, extendMethodName), seqID);
      // 如果游戏不关心同步的调用结果，可以直接返回 null;此处返回同步结果 ”成功“
      return "{\"retCode\":\"0\",\"retMsg\":\"open success\"}";
  }
}

[info] 详情请参考示例代码

2.2 iOS 平台

2.2.1 类规则说明

命名规则：固定为 MSDKExtend + 渠道，如：MSDKExtendGarena
扩展模块不需要实现其他接口，但是 MSDK 对扩展模块的方法签名、方法参数列表、返回值作如下规定：
- 方法签名，必须为 "方法名:seqID:"
- 方法参数列表，有且仅有 NSString * paramsJson, NSString * seqID
  - paramsJson
    NSString * 类型，JSON 格式，为功能所需的参数列表信息。比如 Garena 商城需要 region、roleId、serverId 参数，paramsJson 可以为 {"region":"TW","roleId":234234,"serverId":4}。在方法实现中，需要解析 paramsJson 来获取方法具体所需的参数信息。
  - seqID
    NSString * 类型，MSDK 函数调用序列 ID，用于标记是哪一次函数调用，建议日志中添加对应的标记方便定位问题
- 返回值必须为 NSString * 类型，该值用于给游戏同步返回方法的调用结果
扩展模块中的方法必须在头文件中对外暴露

2.2.2 回调字段说明