获取闪屏布局配置¶
请求参数¶
无路径参数、查询参数和业务正文;不接受客户端指定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实际本机和设备范围以其交付为准。