五步接入

如果你已经拥有可访问的项目 H5 和项目后端，可以按下面顺序完成最小接入。

前置准备

进入流程

用户从云宝小程序点击进入项目后，平台会先为本次进入签发一个短期凭证。这个凭证只用于一次服务端校验。

H5 进入参数

H5 只负责读取平台追加的 URL 进入参数，并把凭证提交给项目后端。H5 不直接校验平台用户身份，也不保存平台密钥。

页面会收到的参数

const query = new URLSearchParams(window.location.search)
const launchParams = {
  projectId: query.get('projectId') || '',
  appId: query.get('appId') || '',
  enterTicket: query.get('enterTicket') || '',
  expiresIn: Number(query.get('expiresIn') || 0),
  source: query.get('source') || '',
  returnUrl: query.get('returnUrl') || '',
}

if (!launchParams.enterTicket) {
  showError('请从云宝小程序入口进入项目')
} else {
  const loginResult = await fetch('/api/yunbao/login', {
    method: 'POST',
    headers: { 'content-type': 'application/json' },
    body: JSON.stringify({
      projectId: launchParams.projectId,
      enterTicket: launchParams.enterTicket,
    }),
  }).then((response) => response.json())

  saveGameSession(loginResult.projectToken)
  startGame()
}

服务端校验

项目后端是接入链路中的可信执行方。你的后端收到 H5 提交的 enterTicket 后，需要调用云宝平台校验接口。

async function verifyYunbaoTicket(enterTicket) {
  const response = await fetch('https://api.example.com/api/v1/open/h5-project-access/verify-ticket', {
    method: 'POST',
    headers: {
      'content-type': 'application/json',
      'x-game-app-secret': process.env.YUNBAO_APP_SECRET,
    },
    body: JSON.stringify({
      appId: process.env.YUNBAO_APP_ID,
      enterTicket,
    }),
  })

  const result = await response.json()

  if (!response.ok || !result.valid) {
    throw new Error(result.message || '云宝平台授权校验失败')
  }

  return result
}

校验成功后你应该做什么

接口说明

平台小程序申请进入凭证

该接口由云宝平台小程序调用，第三方项目方不需要直接调用。

项目后端校验进入凭证

项目后端查询用户持卡状态

curl -X POST 'https://api.example.com/api/v1/open/h5-project-access/verify-ticket' \
  -H 'content-type: application/json' \
  -H 'x-game-app-secret: YOUR_APP_SECRET' \
  -d '{
    "appId": "YOUR_APP_ID",
    "enterTicket": "ENTER_TICKET_FROM_H5"
  }'

错误处理

安全要求

接入检查表

架构与时序图

下面的图用于理解平台、小程序、第三方 H5、项目后端和外部服务的职责边界。正式接入时以上方接口和检查表为准。

总体架构图

进入流程时序图

附录资料

以下是平台内部沉淀的详细设计材料，第三方技术人员通常只需要阅读本文档主体；遇到边界问题时再查阅附录。