五步接入

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

前置准备

进入流程

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

H5 SDK

SDK 的职责是帮助 H5 读取平台进入参数，并把凭证提交给项目后端。SDK 不直接校验平台用户身份，也不保存平台密钥。

页面会收到的参数

import { createYunbaoGameSdk } from './platform-game-sdk'

const sdk = createYunbaoGameSdk()
const launchParams = sdk.getLaunchParams()

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、项目后端和外部服务的职责边界。正式接入时以上方接口和检查表为准。

总体架构图

进入流程时序图

附录资料

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