ZYMIX 小游戏开发者文档 管理后台 · 接口文档 · 开发者文档 · Markdown 源文件

ZYMIX 小游戏开发者文档

> 来源：钉钉知识库《ZYMIX小游戏开发者文档》

>

> 知识库入口：https://alidocs.dingtalk.com/i/nodes/0eMKjyp8130aovvzHekRQdeGVxAZB1Gv

>

> 文档版本：v4.0

>

> 钉钉知识库更新时间：2026-07-16

>

> Markdown 整理日期：2026-09-10

>

> 适用对象：ZYMIX 平台第三方合作商

>

> 说明：本文按钉钉页面当前正文整理，保留原文中的章节、代码、表格、枚举值和外部链接。章节内的内容边界以钉钉原文为准。

目录

0. 知识库总览

原文：0. 知识库总览

ZYMIX 小游戏平台 - 知识库总览

🎯 从这里开始

⭐ 必读：开发者技术接入手册

这份文档包含：

建议所有新加入的开发者首先阅读此文档（约 10 分钟）。

📚 完整文档列表

🔰 入门阶段

1. 开发者技术接入手册 ⭐ 必读

2. 团队与权限管理 - 账号创建、角色分配

3. 角色与职责边界 - 前后端分工

🚀 开发与上架

4. 小游戏上架全流程 ⭐ 核心

5. 登录能力对接 - wx.login、getUserInfoAll

6. 自定义分享规范 - 分享菜单配置

✅ 测试与发布

7. 联调与验收清单 📋 必查

8. 灰度发布指南 - 灰度策略

9. 运营数据查询 - 数据监控

🔒 合规与支持

10. 安全与合规要求 ⚠️ 必须遵守

1. 角色与职责边界

原文：1. 角色与职责边界

1. 小游戏前端开发团队

2. 小游戏后端开发团队

3. Zymix 技术支持与发布负责人（Owner）

2. 小游戏上架全流程

原文：2. 小游戏上架全流程

本文介绍了在 TCMPP/TCSAS 平台创建、配置、上传、审核及发布小游戏的完整流程，涵盖账号开通、开发者工具使用、版本管理与线上运维等环节，旨在指导开发者合规高效地完成小游戏上线。

1. 开通账号与小游戏能力

1. 联系 Zymix 技术支持：

2. 登录控制台，首次登录时修改初始密码。

2. 创建小游戏

操作路径：

小游戏管理 → 小游戏列表 → 创建小游戏

填写以下信息：

创建成功后，系统会生成唯一的小游戏 AppID。

创建权限通常需要“小程序团队管理员”或“小程序高级开发者”角色。

3. 完成上线前配置

进入小游戏的“开发管理”，根据实际功能配置：

如果业务请求域名无法全部固定，可以申请跳过域名校验，但需要由 Super App 管理方审批。

3. 团队与权限管理

原文：3. 团队与权限管理

本手册为 ZYMIX 平台第三方合作商提供账号权限管理的完整操作指南，涵盖子账号创建、角色分配、语言设置及权限验证流程，旨在帮助团队管理员高效安全地配置成员访问权限，确保开发与运营协作顺畅。

1. 文档说明

1.1 目标读者

本手册面向 ZYMIX 平台的第三方合作商，主要包括：

1.2 前置条件

使用本手册前，请确保：

1.3 术语说明

术语 说明
主账号 团队创建者或超级管理员持有的账号
子账号 由主账号创建的团队成员账号
团队角色 决定成员在团队内的功能权限（如开发者、运营人员等）
IDE ZYMIX 开发者工具，用于小游戏开发与调试

2. 快速开始

2.1 登录控制台

1. 访问 ZYMIX 控制台登录页面。

2. 输入账号密码登录。

3. 首次登录建议切换为熟悉的操作语言（参见第 3 章）。

2.2 核心操作流程

4. 技术对接指南

原文：4. 技术对接指南

本文档面向接入 Zymix 宿主 App 的小程序与小游戏开发者，系统说明了从环境准备、JSAPI 调用规范、关键功能接入到联调发布的完整流程，重点强调登录态管理、版本兼容性及错误处理机制，旨在指导开发者高效完成集成与上线。

🎯 本文档定位

这是一份纯技术对接文档，聚焦于：

不包含团队管理、权限分配、角色职责等管理层内容，参见团队与权限管理。

⚡ 5 分钟快速上手

Step 1：环境准备

下载开发者工具
创建项目
IDE → 新建项目 → 选择 AppID → 填写项目名称 → 选择目录

Step 2：核心 API 调用规范

所有自定义 JSAPI 统一入口：

wx.invokeNativePlugin({
  api_name: 'yourApiName',    // 必填，区分大小写
  data: { /* 业务参数 */ },   // 必填，无参数也要传 {}
  success: (resp) => {
    console.log('成功:', resp);
  },
  fail: (err) => {
    const parsed = JSON.parse(err.errMsg);
    console.error(`错误 ${parsed.code}: ${parsed.message}`);
  },
  complete: () => {
    console.log('完成');
  }
});

⚠️ 关键规则：

1. api_name 不是 apiName（下划线命名）。

2. data 必须传 {}，即使没有参数。

3. AppID 自动注入，无需手动传递。

4. 绝大多数 API 要求用户已登录，否则返回 -401。

🐛 全局错误码速查

code message 含义 排查建议
0 success 成功 —
-1 data missing data 字段缺失或不是对象 检查是否传了 {}
-2 appID missing 极少出现 联系技术支持
-3 openID missing 缺少 openId 先调用 bindOpenId
-4 unknown error 兜底错误 查看完整错误信息
-200 network error 网络未连接 检查网络连接
-201 service error 服务端调用失败 重试或联系技术支持
-300 conversation creation failed 创建会话失败（IM） 检查 IM 权限
-301 invalid response 返回内容无法解析 常见：未先调 bindOpenId
-400 invalid notification type 订阅消息 validity 不合法 检查参数值
-401 User is not logged in 用户未登录 Zymix 先调用 getHostUserInfo 确认登录状态

💡 高频错误：-401 是最常见问题，确保在调用任何业务 API 前先确认用户已登录。

5. 登录能力对接

原文：5. 登录能力对接

用户已在 ZYMIX App 登录的前提下，小游戏通过 wx.login 无感获取 code，后端换 openid 建立登录态，再调用 getUserInfoAll 获取头像昵称等信息用于前端展示，实现免登录体验。核心是登录与信息展示分离。

适用对象：ZYMIX App 内小游戏开发商。

核心流程：wx.login → 后端换票 → getUserInfoAll → 页面展示。

1. 方案说明（先看这个）

用户在 ZYMIX App 里已经登录，进入小游戏时：

1. 用 wx.login 完成平台登录（可无感，不用弹窗）。

2. 小游戏后端用 code 换 openid，建立登录态。

3. 用 getUserInfoAll 拿头像、昵称等，直接在游戏里展示。

接口 做什么 能不能省
wx.login 平台登录、换 openid ❌ 不能省
getUserInfoAll 拿头像昵称做 UI 展示 ✅ 展示场景用这个

2. 整体流程（4 步）

① 小游戏调用 wx.login，拿到 code
        ↓
② 把 code 发给小游戏后端 → 后端调 jscode2session → 得到 openid
        ↓
③ 后端返回 token 给小游戏（openid 留在服务端）
        ↓
④ 小游戏调用 getUserInfoAll → 拿 avatar、nickName 等 → 直接展示

3. 对接步骤

步骤 1：小游戏前端调用 wx.login

wx.login({
  success(res) {
    if (res.code) {
      // 把 code 发给后端
      doLogin(res.code);
    }
  }
});

6. 自定义分享规范

原文：6. 自定义分享规范

小游戏在 Zymix 平台实现分享功能需遵循特定规范，包括参数范围、回调设置及渠道可用性。文章旨在明确分享机制的技术要求与限制，确保开发者正确集成分享功能，最终结论为仅“分享给 Zymix 好友”为有效渠道，其余系统渠道不可用。

1. 核心规则

2. 分享渠道

3. 接入代码

// 开启分享菜单
wx.showShareMenu({
  shareKey: 'wechatFriends'
});

// 注册分享回调
wx.onShareAppMessage(() => {
  return {
    title: '小游戏分享标题',
    imageUrl: 'https://example.com/share.png',
    query: 'id=150&from=share'
  };
});

其中：

7. 小游戏激励广告接入

原文：7. 小游戏激励广告接入

本文面向小游戏开发者，指导其在 TCSAS 平台申请激励视频广告位及前端对接流程，明确运行环境、申请步骤、代码封装与发奖逻辑，确保合规集成并避免常见错误。

面向小游戏开发者：如何在 TCSAS 平台申请激励广告位，以及如何在前端完成对接。

仅覆盖激励视频广告（Rewarded Video）。插屏、Banner、原生模板等不在本文范围内。

运行环境：Zymix 宿主 App 的 wx API 小游戏环境；Zymix 版本 Android ≥ 1.1.4，iOS ≥ 1.1.14。

1. 接入概览

开发者侧完整路径：

小游戏在 TCSAS「我的广告单元」申请使用广告单元
        │
        ▼
等待 Super App 审批通过，拿到 adUnitId
        │
        ▼
前端 wx.createRewardedVideoAd 对接激励视频
        │
        ▼
仅在 onClose 且完整观看后发放奖励

核心原则：

1. 广告实例只创建一次并复用：createRewardedVideoAd 返回全局单例，重复调用返回同一个对象，事件监听只需注册一次。

2. 激励视频以“完整观看”为发奖依据：只有 onClose 回调中 res.isEnded === true（或低版本 res === undefined）才发放奖励，中途关闭不发奖。

3. 展示失败要有兜底：show() 失败时先 load() 再 show()，仍失败则走降级逻辑（提示无广告或分享兜底）。

4. 广告位 ID 由配置下发：adUnitId 从配置读取，不硬编码在业务逻辑里。

2. 前置条件

项目 要求
运行环境 Zymix 小游戏，Android ≥ 1.1.4，iOS ≥ 1.1.14
平台能力 Super App 已启用广告功能（由 Super App 团队完成授权与广告单元同步）
广告位 已在 TCSAS「我的广告单元」申请并通过审批，拿到激励视频 adUnitId
广告位配置 adUnitId 通过配置下发（如 WX_CONFIG.AD_ID.video）

8. 联调与验收清单

原文：8. 联调与验收清单

1. 联调环境准备

2. 验收清单

登录链路

宿主 JSAPI

分享链路

发布前检查

4. Clear Cache 机制（Debug/TestFlight 专属）

在小程序内点右上角胶囊 → 分享菜单 → 「Clear Cache」。

效果：清空缓存、重置一键免弹授权状态。

9. 灰度发布指南

原文：9. 灰度发布指南

1. 背景与目标

灰度发布可以将新版本先推送给部分目标用户，验证稳定性后再逐步全量上线，降低发布风险。

2. 灰度条件类型

类型 说明 适用场景
GUID（系统设备标识） SDK 自动生成，无需业务接入 设备级随机灰度
自定义设备 ID 初始化时设置 deviceUID 内部测试机、特定硬件批次
用户 ID 登录后调用 TmfMiniSDK.setUserId VIP 用户、A/B 实验、白名单

3. 控制台操作流程

1. 登录 TCMPP 控制台。

2. 进入“小程序管理 → 版本管理 → 灰度发布”。

3. 点击“新建灰度任务”。

4. 配置基础信息：

5. 配置灰度条件（GUID/设备 ID/用户 ID）。

6. 提交任务，观察崩溃率、核心指标。

7. 逐步扩大流量，最终全量发布。

4. GUID 获取方式

NSString *guid = [[TMFMiniAppSDKManager sharedInstance] getGuid];

5. 标识策略选型建议

6. 常见问题

Q：同一设备重装后灰度命中变化？

A：GUID 可能在卸载重装后变化，可改用自定义设备 ID 或用户 ID。

Q：用户未登录时能否按用户灰度？

A：不能。用户 ID 维度依赖登录后上报，未登录请用 GUID 或设备 ID。

10. 运营数据查询

原文：10. 运营数据查询

一、适用人员

以下角色均可查看数据概览：

二、操作入口

1. 登录 TCSAS 控制台。

2. 进入对应的 Superapp。

3. 打开“运营管理 > 应用数据概览”。

4. 将“类型”设置为仅小游戏。

三、查询条件

根据分析目标设置。

11. 安全与合规要求

原文：11. 安全与合规要求

1. 必须执行项

2. 用户数据隐私

12. 常见问题（FAQ）

原文：12. 常见问题（FAQ）

一、JSAPI 调用问题

Q1：调用 JSAPI 完全没有回调？

A：检查 api_name 大小写（区分大小写）、data 是否传了 {}。如果只有 complete 没有 success/fail，可能是宿主未注册该 API。

Q2：总是返回 -401 User is not logged in？

A：用户在 Zymix 内未登录。先调用 getHostUserInfo 确认 userId > 0，否则引导用户登录 Zymix。

Q3：IM 接口返回 -301 invalid response？

A：没有先调用 bindOpenId。请先绑定 openId。

Q4：拿不到 gender/city？

A：Zymix 不收集这些字段，始终返回空字符串。需要这些信息请通过自己的后端补全。

二、分享功能

Q1：分享菜单里看不到“分享给 Zymix 好友”？

A：检查是否调用了 wx.showShareMenu，以及是否实现了 onShareAppMessage。

三、音频与震动

Q1：Android 端小游戏无声音？

A：检查 WebAudio 相关扩展依赖是否集成。

Q2：小游戏震动按钮无震动反馈？

A：接入平台 vibrateShort/vibrateLong 标准震动 API，即可正常调用设备震动能力。

Q3：iOS 体验版录音初始化失败（Recorder error）？

A：需明确参数传值，应使用 auto。

13. 参考文档与资源

原文：13. 参考文档与资源

1. 官方文档