扫码测试适配

背景

平台方在正式接入 mPaaS AI 内容魔方后，用户通过扫码测试打开的是平台自身的 App。小游戏资源包也应通过平台自有 CDN、包管理服务和端侧拉包逻辑进行加载。

为支持内容魔方为平台选品的小游戏生成体验二维码，需向内容魔方提供平台侧的 URL 解析逻辑。

平台方需完成的三类适配

在接入 mPaaS AI 内容魔方后，平台方需完成以下三类关键适配工作，以保障用户扫码体验小游戏的完整性与一致性：

1. 提供可被平台 App 识别的 URL 协议模板
   平台需定义一个能被 App 正确识别并跳转的 URL 协议，这个模板可以是 App scheme，也可以是 universal link，只要平台 App 能识别并打开即可。
   

   yourapp://minigame/open?appId={appId}&version={version}&type={type}

2. 实现 URL 参数解析逻辑
   平台 App 需具备从 URL 中提取关键参数（如 appId、version、type 等）的能力，并根据这些参数加载对应的资源包。建议适配 mPaaS 提供的标准字段命名规范。
   

3. 向 mPaaS 提交 URL 模板，用于生成体验二维码
   为支持 mPaaS 为平台选品的小游戏生成体验二维码，平台需提供完整的 URL 构造规则。mPaaS 将基于此规则动态生成 QR Code，确保用户扫码后能正确打开对应小游戏。
   

为什么要适配 mPaaS 通用 URL 模板

在接入 mPaaS AI 内容魔方的过程中，平台方通常已经拥有完整的 App 唤起协议、CDN 域名、资源包服务、灰度/白名单体系和小游戏运行容器等基础设施。

如果内容魔方为每个平台硬编码一套二维码生成逻辑，将导致：

• 每次新增平台都需对内容魔方系统进行版本更新；

• 平台协议变更后，内容魔方也需要同步修改相关逻辑。

为了解决上述问题，我们推荐采用 通用 URL 模板机制。

通用 URL 模板的目标是明确划分平台方与内容魔方之间的职责边界。

平台方只需与内容魔方约定一个稳定的 URL 模板。后续在该平台下新增小游戏时，可直接复用该模板生成二维码，无需重新开发相关逻辑。

内容魔方二维码 URL 适配规则

内容魔方可通过预设的 URL 模板为平台生成二维码。目前支持以下变量用于动态填充：

平台方支持两种 URL 模板配置方式：平台级模板 和 小游戏级模板。

平台级模板（推荐）

如果平台的业务逻辑能够直接将内容魔方提供的小游戏 ID 作为自身的游戏标识，无需额外转换或映射，则建议统一配置平台级模板。

模板配置示例

templateUrl = yourapp://minigame/open?appId={appId}&version={version}

渲染结果示例

yourapp://minigame/open?appId=9999123456789116&version=1.0.62.8

平台客户端扫码后解析

{
  "appId": "9999123456789116",
  "version": "1.0.62.8"
}

平台方将根据解析出的参数，调用自身的包管理服务，查询并下载对应版本的小游戏资源包。

小游戏级模板（不推荐）

如果平台方不通过小游戏自身的 code 拉取包体，而是使用平台侧统一的小游戏密钥进行拉取，则内容魔方侧需为每个小游戏配置其在平台侧对应的小游戏密钥。此时可采用“小游戏级模板”进行管理，通过 gameKey 字段标识平台侧对应的小游戏。

模板配置示例

miniProgramCode = 9999123456789116
gameKey = 35363443
templateUrl = yourapp://minigame/open?gameKey={gameKey}&version={version}

渲染结果示例

yourapp://minigame/open?gameKey=35363443&version=1.0.62.8

平台客户端扫码后解析

{
  "gameKey": "35363443",
  "version": "1.0.62.8"
}

典型平台示例

https://platform1-cdn.example.com//applets/platformapi/startgameapp?gameCode=9999123456789116&version=1.0.62.8&type=EXPERIENCE

https://platform1-cdn.example.com//applets/platformapi/startgameapp?gameCode={appId}&version={version}&type={type}

http://www.example2.cn/?qk_tech=native&qk_biz=tinyapp&qk_module=tinyapp_open&qk_params={"type":"qkminigame","appId":"9999123456789116","version":"1.0.62.8","entry":"deeplink_test"}

http://www.example2.cn/?qk_tech=native&qk_biz=tinyapp&qk_module=tinyapp_open&qk_params={"type":"qkminigame","appId":"{appId}","version":"{version}","entry":"deeplink_test"}

app3://mpaas/openApp?gameType=2&appId=99999999&showTitleBar=1&transparentTitle=always