External Delivery Guide

GoodRoad 外网嵌入说明

这份页面是可以直接部署给第三方阅读的在线接入文档。 它和预览页放在同一个目录中，第三方不需要了解仓库结构，只需要访问这个站点即可获得示例、流程和排障说明。

最小接入
1 个容器 + 1 个 CSS + 1 个 JS 纯 HTML 方案不需要手写初始化代码，插件会自动 bootstrap。
预览入口
./index.html 这是第三方首先打开的效果页，适合演示与联调前确认。
资源清单
./assets/manifest.latest.json 用于确认当前页面绑定的是哪一版 CSS 和 JS 资源。

1. 推荐发布目录

打开效果预览

建议把整个目录原样部署到你的 CDN 或静态站点，至少包含下面这些文件：

/index.html
/guide.html
/assets/goodroad-widget.css
/assets/goodroad-plugin.dev.protected.js
/assets/manifest.latest.json
如果你已经生成了正式环境保护包，可以直接覆盖 assets/goodroad-plugin.dev.protected.js，并把说明文字改成 prod 版本即可。

2. 纯 HTML 嵌入

这是当前最适合发给第三方的纯 HTML 示例。不写初始化脚本，直接用容器属性完成演示默认值配置。

<link rel="stylesheet" href="./assets/goodroad-widget.css" />
<div
  data-goodroad-widget
  data-goodroad-api-base="http://127.0.0.1:13100"
  data-goodroad-channel-id="demo-channel"
  data-goodroad-limit="8"
></div>
<script src="./assets/goodroad-plugin.dev.protected.js"></script>
上面这段示例使用的是当前联调默认值。真正发到正式外网时，请把 apiBase、channelId 和脚本版本替换为你的正式配置。

3. 标准 mount 模式

如果第三方需要传会员 token、签名头、回调或埋点，请改用 GoodRoadWidget.mount()。

<div id="goodroad-root"></div>
<link rel="stylesheet" href="./assets/goodroad-widget.css" />
<script src="./assets/goodroad-plugin.dev.protected.js"></script>
<script>
  var widget = window.GoodRoadWidget.mount({
    container: '#goodroad-root',
    token: window.USER_TOKEN || '',
    signer: async function (ctx) {
      return {
        'x-signature': await fetch('/goodroad/signature', {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify(ctx)
        }).then(function (r) { return r.json(); }).then(function (x) { return x.signature; })
      };
    },
    onPluginError: function (error) {
      console.warn('[GoodRoad][PluginError]', error.code, error.message, error);
    },
    onStateChange: function (state) {
      console.log('[GoodRoad][State]', state.state, state);
    },
    onEnterGame: function (payload, item) {
      console.log('[GoodRoad][EnterGame]', payload, item);
    }
  });

  widget.ready.catch(function (err) {
    console.error('[GoodRoad][ReadyFailed]', err);
  });
</script>

4. 部署流程

联调预览

  1. 部署整个 public-embed 目录。
  2. 先打开 index.html 查看展示效果。
  3. 再打开 guide.html 给第三方看接入说明。

正式发布

  1. 将示例中的默认联调值替换为正式值。
  2. 将当前 dev 保护包替换为正式保护包。
  3. 通过真实 http(s) 域名访问，不要以 file:// 方式做最终验收。
场景 推荐脚本 是否需要手写参数 说明
本地 / 内网联调 goodroad-plugin.dev.protected.js 通常不需要 快速预览效果最方便。
正式外网交付 goodroad-plugin.prod.protected.js 视方案而定 零代码模式可写在 data 属性里，标准接入可走 mount。
带 token / 签名 / 回调 goodroad-plugin.prod.protected.js 需要 使用 mount() 方式更可控。

5. 后端接口约定

POST /api/plugin/v1/init-ticket
POST /api/plugin/v1/session/exchange
GET  /api/plugin/v1/tables/snapshot
POST /api/plugin/v1/game/enter
  • x-session-token 是 snapshot 与 enter 的首选会话传输方式。
  • 游客可以看桌台列表，但不能进入游戏。
  • 如果启用了签名校验，请通过服务端生成签名，不要把密钥放在前端。
  • 如果启用了域名白名单，第三方页面域名必须已授权。

6. 常见问题

页面空白或一直 initializing
优先检查脚本文件是否可加载、后端地址是否可访问，以及当前域名是否已授权。
点击进入提示需要登录
说明当前是游客会话，请切换到 mount() 方案透传 token。
联调没问题，正式外网失败
检查是否还在使用 dev 默认值，或外网域名是否未加入 allowlist。
第三方只拿到了 guide，没有效果页
建议始终把 index.html 和 guide.html 一起发布。