Portal 便捷登录

如果不希望自行开发二维码展示和轮询页面，可以把用户跳转到 Cool Login 的便捷登录页。用户扫码成功后会自动返回你的应用，你的服务端使用返回的 ticket 查询一次现有登录状态即可取得受保护的用户标识。

1. 发起跳转

将用户跳转到：

https://cool-login.qdoc.fun/portal/login?appId=你的-App-ID&redirectUri=编码后的返回地址

例如，返回地址为 https://example.com/auth/callback?from=login 时，需要先进行 URL 编码。页面会展示 App 名称和返回域名，让用户确认登录目标。

redirectUri 建议始终显式提供。未提供时页面会尝试使用浏览器记录的来源地址，但浏览器隐私设置可能不会提供该地址。返回地址只允许使用 HTTP 或 HTTPS，生产环境应使用 HTTPS。

2. 接收登录结果

扫码成功后，页面会返回原地址并保留已有查询参数，同时增加：

参数	说明
`appId`	发起本次登录的 App ID
`ticket`	Portal 展示二维码时使用的原登录票据

例如：

https://example.com/auth/callback?from=login&appId=cl_app_xxx&ticket=cl_xxx

3. 获取用户身份

你的服务端使用现有 HMAC 签名规则调用原有登录状态接口：

GET /api/open/login/status?ticket=cl_xxx

签名请求头中的 App ID 必须和返回参数中的 appId 一致。成功响应：

{
  "success": true,
  "data": {
    "ticket": "cl_xxx",
    "status": "success",
    "unionUserId": "cl_union_v1_xxx",
    "appUserId": "cl_app_user_v1_xxx"
  }
}

unionUserId 在当前开发者名下的全部 App 中保持一致，适合共享账号；appUserId 只在当前 App 中保持一致，适合独立账号。它们均不是微信原始 OpenID 或 UnionID。

扫码成功结果只保留 30 秒。回跳后应立即由你的服务端查询一次登录状态；不要在浏览器里生成签名或暴露 App Secret。

两种接入方式如何选择

方式	适合场景	你需要实现
自建扫码页	需要完全控制页面布局和登录过程	请求二维码、展示二维码、轮询状态
Portal 便捷登录	希望快速完成接入	跳转、接收原 ticket、服务端查询一次状态

两种方式共用同一个 App、套餐额度和登录统计。只有微信身份确认成功才累计月登录次数。