SDK 程序配置、公告与版本

程序配置

GEThttps://gnyanzheng.cn/api/v1/apps/configClient::app_config

返回 app_id、project_name、status、verify_enabled、heartbeat_interval、session_ttl、timestamp_tolerance、version_code 和 version_name。客户端应使用服务端返回的间隔和时间窗，不要写死。

程序公告

GEThttps://gnyanzheng.cn/api/v1/apps/announcementClient::announcement

返回 title、content 和 updated_at。正文为空属于正常状态。客户端列表只显示标题，用户主动打开后再显示全文，并用更新时间避免重复弹出。

版本检查

GEThttps://gnyanzheng.cn/api/v1/apps/versionClient::version

传入 current_version_code。服务端只选择最高的已启用 version_code；version_name 不参与大小比较。

更新清单可能包含：

• has_update：是否存在更高版本。
• file.download_url：短期有效下载地址。
• file.size：期望文件大小。
• file.sha256：完整文件 SHA-256。
• sdk_release：当前平台发布的 SDK 版本、文件名、哈希和说明。

更新器职责

SDK 只返回清单，不会下载、安装或替换程序。客户端必须下载到临时文件，同时校验大小和 SHA-256，校验成功后退出主程序并交给独立更新器替换。临时地址过期后重新调用版本接口。

更新事件回报（可选）

POSThttps://gnyanzheng.cn/api/v1/update/events更新分析

用于把客户端的更新漏斗回报给平台，作者可在程序「更新分析」页查看汇总。这是可选接口：不上报不影响登录、心跳或更新检查。

请求头与 SDK 其他 /api/v1 接口相同（X-GN-App-Id、X-GN-Timestamp、X-GN-Nonce、X-GN-Signature、X-GN-Key-Id）， 并且必须额外携带有效卡密会话令牌：

POST /api/v1/update/events
X-GN-App-Id: 程序ID
X-GN-Timestamp: 1720000000
X-GN-Nonce: UNIQUE_NONCE
X-GN-Key-Id: project
X-GN-Signature: 64位大写HMAC-SHA256
X-GN-Session-Token: 卡密登录返回的 session_token
Content-Type: application/json

{
  "event_type": "download_completed",
  "machine_id": "卡密登录时使用的设备码",
  "client_version": "1.2.0",
  "target_version": "1.3.0",
  "platform": "windows",
  "architecture": "x64",
  "failure_code": ""
}

event_type 只接受以下 8 个值，其它值返回 422：

check  update_available  token_issued  download_started
download_completed  download_failed  checksum_failed  client_reported_installed

要点：

• 会话令牌无效、设备码不匹配或会话已吊销时返回 401，事件不会入库。
• machine_id 必须与卡密登录时绑定的一致；服务端据此解析会话。
• 服务端只保留白名单字段（machine_hash、client_version、target_version、platform、 architecture、failure_code、session_id、card_id、app_user_id、request_id、ip_address）， 其余字段被丢弃；元数据超过 4096 字节时整条替换为 {}。
• 成功响应固定为 {"success":true,"code":0,"message":"success","data":{"accepted":true}}。
• machine_hash 必须是 64 位十六进制，否则按空值记录（不会导致请求失败）。