GET/api/v1/app/bootstrap
匿名App,八项公共请求头;正式HTTPS/JWEJSON 响应接入指南 ↗

获取闪屏布局配置

请求参数

无路径参数、查询参数和业务正文;不接受客户端指定IP、国内/国际、商店国家或用户资料国家。查询参数即使为空也返回400。八项公共请求头必填,X-Client-Type固定app,平台仅android/ios;已知发行渠道与平台必须匹配,dev及其他格式合法渠道也可以使用本布局接口。

不需要登录,也不要主动附带Bearer;携带无效、重复或不匹配安装的凭据仍返回401。正式要求HTTPS及JSON/JWE,GET密文置于X-Budyoo-JWE;开发固定模式沿用现有明确HTTP明文兼容,但本接口发送JWE仍必须HTTPS,HTTP密文返回426,不关闭TLS或响应认证。

服务端只读取可信Nginx及Tomcat解析后的连接来源地址。公网客户端自行填写X-Forwarded-For、X-Real-IP、Forwarded等不能覆盖来源。IP库只用于布局,不作为身份、账号永久地区、付款归属或法律适用的证明。

请求示例

以下为合成元数据的开发明文兼容请求。正式在同一方法和路径使用既有加密封装,不能直接复制到生产明文调用。

GET /api/v1/app/bootstrap HTTP/1.1
Accept: application/json
Accept-Language: en
X-Client-Type: app
X-Platform: ios
X-App-Version: 1.0.0
X-App-Build: 1
X-Channel: app_store
X-Device-Id: 11111111-1111-4111-8111-111111111111
X-Request-Id: 22222222-2222-4222-8222-222222222222
X-Request-Timestamp: <当前Unix毫秒>

成功响应

HTTP200,Cache-Control:no-store。来源IP识别为中国大陆但界面选择英文时,解密后示例:

{
  "code": "SUCCESS",
  "message": "Operation completed.",
  "data": {
    "layoutRegion": "domestic",
    "regionSource": "IP",
    "countryCode": "CN",
    "language": "en",
    "policyVersion": "ip-v1",
    "countryDatabaseVersion": "dbip-country-lite-2026-11"
  },
  "errors": []
}
data字段 类型 可空 说明
layoutRegion string 否 domestic国内/overseas国际;未知默认domestic,不返回unknown
regionSource string 否 IP表示国家库命中;DEFAULT表示无法识别而使用国内默认
countryCode string 是 IP命中的ISO两位大写代码,CN映射国内;其他已识别地区含HK/MO/TW映射国际;回退为null,不伪造CN
language string 否 当前界面语言归一值zh-CN/en/ja/ko;未知或缺省en,与IP布局独立
policyVersion string 否 当前固定ip-v1;用于客户端检查是否支持此规则
countryDatabaseVersion string 否 当前实际加载的离线库版本,更新后可能变化,不写死为单一月份

无法识别、回环/私网/保留地址及运行时查询失败时仍返回HTTP200:layoutRegion=domestic、regionSource=DEFAULT、countryCode=null。发行来源不变:app_store始终苹果渠道,Xiaomi包在海外IP也可获得国际布局。不会改用户UUID、资料国家、关系、钱包、会员权益或订单。

失败响应

HTTP code 条件
400 INVALID_CLIENT_HEADERS 必填元数据缺失/重复/格式错误,已知渠道与平台不符
400 BAD_REQUEST 携带任何查询参数
400 ENCRYPTION_REQUIRED/INVALID_ENCRYPTED_REQUEST 当前模式要求JWE,或信封/上下文校验失败
401 UNAUTHORIZED 主动携带的凭据失效、非法或与安装不符
403 FORBIDDEN 非App客户端类型
426 HTTPS_REQUIRED 当前安全策略要求HTTPS
429 TOO_MANY_REQUESTS 网关限流
503 SERVICE_UNAVAILABLE 加密防重放等依赖不可用
{"code":"BAD_REQUEST","message":"请求格式不正确。","data":null,"errors":[]}

固定code不翻译,message和字段错误按Accept-Language四语输出。网络失败、超时、HTTP错误、JSON/JWE认证失败不属于“IP未知”,前端不能自行当domestic放行。

接入说明

冷启动顺序为共用闪屏→成功读取本接口并应用本轮layoutRegion→显示对应协议/布局→协议选择结束后并发检查升级及auth/options→两项都成功再继续登录或恢复会话。启动失败沿用不可取消重试,禁止回退、蒙层或Escape绕过;每次重新冷启动读取当前IP,避免把首次网络出口永久绑定给账号。

注册/编辑/购买等在途页面不因网络切换突然改布局。新客户端读取协议目录必须传唯一查询layoutPolicy=ip-v1;目录与闪屏使用同一服务器规则,国内正文中文,国际正文随Accept-Language选四语。若网络变化导致目录serviceRegion与本轮布局不符,重新获取两项并阻止混用与自动同意,不以客户端自报地区强制覆盖后端判断。

版本更新仍按发行渠道和真实构建号查询。苹果商店商品、价格、币种和交易核验继续按平台流程;IP布局不替代支付依据。真实支付不在本接口范围。

IP国家库为DB-IP Country Lite,CC BY 4.0,署名:IP Geolocation by DB-IP。固定月度快照随应用发布、启动校验SHA256、IPv4/IPv6本地查询,不为每次请求访问第三方,不记录原始IP到本接口响应或账号表。Lite覆盖和精度有限,VPN/代理按网络出口判断;库缺失或损坏阻止启动,不冒称正常识别。当前没有自动更新国家库。

2026-11-04已部署,401项完整服务器Java回归通过(0失败/0跳过),包含真实国家库IPv4/IPv6、特殊地址默认、不同渠道/语言、来源头防伪、安全链、JWE和协议新旧模式兼容。公网41组检查(含24组bootstrap+协议配对)通过,实际公网出口识别为CN/domestic/IP;服务器回环隔离HTTPS另41组通过,DEFAULT国内与真实双向JWE均验证,证书链和IP名称验证保持开启。HTTP业务密文426符合原契约。隔离HTTPS探针完成后已关闭,不表示公网正式HTTPS已开通。

公开验收脚本为deploy/experience/verify-live.mjs,无登录/账号/版本发布/支付写入;运行库仍V18。海外IP、IPv6和混合范围来自服务器隔离测试注入的remoteAddr及真实国家库,不宣称在不同国家真机完成验收。Flutter实际本机和设备范围以其交付为准。