官方 SDK 接口总览

官方 C++ SDK 使用固定的 /api/v1 协议。这里的 v1 是 SDK API 版本，与项目设置里的 Legacy V1/Legacy V3 无关。SDK 不调用 /api/card_login，也不调用 /api/legacy/v3/*。

SDK 能力矩阵

Client 方法	HTTP 路由	用途	接口授权 key
`app_config()`	`GET /api/v1/apps/config`	程序状态、心跳间隔、会话期限与版本	`app_config`
`announcement()`	`GET /api/v1/apps/announcement`	当前程序公告	`announcement`
`version(code)`	`GET/POST /api/v1/apps/version`	更新清单、临时下载地址与 SDK 版本	`latest_version`
`card_login()`	`POST /api/v1/cards/login`	卡密登录并创建会话	`card_login`
`card_heartbeat()`	`POST /api/v1/cards/heartbeat`	维持卡密会话、接收下线状态	复用 `card_login`（不重复计量）
`card_unbind()`	`POST /api/v1/cards/unbind`	使用当前 Bearer 会话解绑设备	`card_unbind`
`verify_domain()`	`POST /api/v1/domains/verify`	验证项目下的域名授权	`check`
`user_register()`	`POST /api/v1/users/register`	注册当前项目的程序用户	`app_user_register`
`user_login()`	`POST /api/v1/users/login`	程序用户登录并创建会话	`app_user_login`
`user_heartbeat()`	`POST /api/v1/users/heartbeat`	维持程序用户会话	复用 `app_user_login`（不重复计量）
（无 SDK 方法）	`POST /api/v1/update/events`	可选：回报客户端更新漏斗事件	无（只要求有效卡密会话）

平台内置的全部接口授权 key（用户端接口中心显示的即为这些）： card_login、announcement、unbind_machine、latest_version、legacy_connect、 app_user_login、app_user_register、check、app_config、get_file、app_profile、 paycheck、core、download。其中 card_login、announcement、unbind_machine、latest_version 构成基础接口包； core（旧版域名授权验证）不在基础包内，需作者按项目单独开通。

POST /api/v1/update/events 是唯一不检查接口开通与配额的 /api/v1 接口：它只校验 SDK HMAC 与有效卡密会话，避免可选的分析上报因为接口未开通而影响客户端更新流程。

每次请求都需要

X-GN-App-Id：用户中心显示的程序 ID。
X-GN-SDK-Version：当前 SDK 版本，低于平台或项目最低版本会被拒绝。
SDK HMAC-SHA256 签名、秒级时间戳和唯一 nonce。
HTTPS、证书校验和与最终发送内容一致的请求体哈希。

服务端会先校验 HMAC、时间戳和 nonce，再返回 SDK 总开关、项目停用、验证开关、最低版本或接口开通状态。签名失败的请求不能用来探测这些运行状态；失败重试必须生成新的时间戳和 nonce。

SDK 签名原文固定为：

text

HTTP_METHOD
/v1/route/path
timestamp
nonce
lowercase_sha256_of_raw_body

统一响应

json

{
  "success": true,
  "code": 0,
  "message": "success",
  "request_id": "...",
  "server_time": 1780000000,
  "data": {}
}

客户端首先判断 SDK Result.success，再读取 data。不要把 HTTP 200、code 或某个业务字段单独当作所有 SDK 方法的统一成功规则。

SDK 1.2.0 起提供 Result.clock_skew_seconds，表示服务端时间减去本机请求时间。签名持续出现时间戳错误时可据此提示用户校准系统时钟，但客户端不能自行篡改签名时间绕过服务端时间窗。

SDK 1.2.x 会话管理

card_login() 成功后可直接调用无参数 card_heartbeat()，解绑可调用 card_unbind(card_code)。
user_login() 成功后可直接调用无参数 user_heartbeat()。
has_card_session() 与 has_user_session() 只报告当前 Client 内存中是否有对应会话，不代替服务端心跳验证。
主动退出时调用 clear_card_session()、clear_user_session() 或 clear_sessions()；这些方法会覆盖对应的令牌与设备缓存。
1.1.0 的显式 token 重载全部保留。不要同时在多个线程中销毁同一个 Client；正常并发读取和会话缓存更新由 SDK 内部同步。

官方 SDK 接口总览 ​

SDK 能力矩阵 ​

每次请求都需要 ​

统一响应 ​

SDK 1.2.x 会话管理 ​

推荐调用顺序 ​

官方 SDK 接口总览

SDK 能力矩阵

每次请求都需要

统一响应

SDK 1.2.x 会话管理

推荐调用顺序