8.3 KiB
skin_config.example.json 字段说明
本文档对应仓库内示例文件 lib/src/config/skin_config.example.json。宿主应将复制后的文件放在 assets/skin_config.json（或自定义路径），并在启动时调用 ClientBootstrap.initFromAsset(...)。
1. 根结构概览
| 顶层键 | 必填 | 说明 |
|---|---|---|
app |
是 | 应用展示名、业务 id、包名 |
api |
是 | 环境域名、代理路径、AES 密钥等 |
backend |
否 | fast_login / common_info 等接口的 app 渠道参数 |
videoHome |
否 | 视频首页「Images」虚拟 Tab 的文案与排序 |
proxyKeys |
否 | 代理请求最外层 JSON 的字段名 |
v2 |
否 | 代理 V2 包装壳（层级、业务载荷路径、噪音键） |
fieldMapping |
否 | 逻辑字段名 ↔ 线网/网关字段名；空或省略则恒等映射 |
analytics |
否 | Adjust / Facebook 初始化参数 |
adjustEvents |
否 | 语义化事件名 → Adjust Dashboard 事件 token（供 AnalyticsEvents 等使用） |
extConfig |
否 | common_info.extConfig 的键名模式、任务项映射、本地默认值 |
2. app
| 字段 | 类型 | 说明 |
|---|---|---|
name |
string | 应用名称（必填，非空） |
id |
string | 业务侧应用标识（必填） |
packageName |
string | 应用包名；用于请求头 pkg 等（必填） |
3. backend
省略时框架使用默认值：iosAppType → HIOS，androidAppType → HAndroid。
| 字段 | 类型 | 说明 |
|---|---|---|
iosAppType |
string | iOS 上部分接口 query app 的值 |
androidAppType |
string | Android 上同上 |
4. videoHome
用于 VideoHomeRuntime 与 AppConfig 中与首页 Tab 相关的展示配置。
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
imagesTabLabel |
string | Images |
与接口分类并列的「运营位 / Images」Tab 文案 |
imagesTabFirst |
bool | false |
为 true 时该 Tab 排在服务端分类之前 |
5. api
| 字段 | 类型 | 说明 |
|---|---|---|
preBaseUrl |
string | 预发环境 API 根地址（必填） |
prodBaseUrl |
string | 生产环境 API 根地址（必填） |
proxyPath |
string | 代理入口路径，如 /v1/proxy（必填） |
aesKey |
string | AES-128 密钥字符串，当前实现为 16 字符（必填） |
debugBaseUrlOverride |
string | null | 仅 Debug 构建有效：非空时覆盖 preBaseUrl，用于本地/抓包代理 |
alwaysUsePreBaseUrl |
bool | 为 true 时 任意构建类型下 baseUrl 始终为 preBaseUrl（便于长期连预发）；Release 若仍访问预发，优先检查此项是否为 true |
baseUrl 选择规则（SkinConfig.baseUrl）
- 若
alwaysUsePreBaseUrl == true→preBaseUrl - 否则若 非 Debug（Release/Profile）→
prodBaseUrl - 否则（Debug）→
debugBaseUrlOverride ?? preBaseUrl
6. proxyKeys
定义代理请求明文 JSON 最外层的键名；值为密文或内嵌结构，具体与后端约定一致。省略时框架使用内置默认字段名（如 appId、path、method、headers、params、body 及默认 noiseKeys）。
| 字段 | 说明 |
|---|---|
appIdField / pathField / methodField / headerField / paramsField / bodyField |
各语义段字段名 |
noiseKeys |
噪音字段名列表，用于 V2 代理外层填充随机串 |
7. v2
与 AppConfig 中 V2 包装一致：在 proxyKeys 体内部再包一层固定壳，业务密文放在 sanctumPath 末端。
| 字段 | 说明 |
|---|---|
levelField |
最外层固定层级字段名（如 level） |
levelFixedValue |
该字段固定整型值 |
sanctumPath |
从根到业务载荷的键路径，如 ["wrapper","layer","payload"] |
noiseKeys |
与 level 同层的噪音键名列表 |
8. fieldMapping
Map：逻辑名 → 线网名。请求发出前将逻辑字段映射为线网字段，响应解析后再映射回逻辑名。示例中 code→httpCode、msg→message、data→payload 表示网关使用另一套顶层键名。空对象或省略表示恒等映射（kIdentityFieldMapping）。
9. analytics
传给 SkinConfig.buildAnalyticsConfig 以初始化 Adjust / Facebook。占位 token（如含 your_、example.com）会被识别为无效并跳过对应 SDK，避免带着假密钥初始化。
| 字段 | 说明 |
|---|---|
debugLogs |
框架侧调试输出开关（与各 SDK 内日志配合） |
adjust.appToken |
Adjust App Token |
adjust.environment |
sandbox / production（其它值按 production 处理） |
adjust.logLevel |
如 verbose / off |
adjust.fbAppId |
可选，供 Adjust 与 Meta 相关能力 |
facebook.appId |
Facebook 应用编号 |
facebook.clientToken |
客户端口令；可为空字符串（若业务允许） |
facebook.debugLogs |
Facebook SDK 侧调试日志 |
另支持根级 platformAttribution 等扩展（见源码 buildAnalyticsConfig）。
10. adjustEvents
键：框架内使用的逻辑事件名（如 register、purchase、firstPurchase、paymentFailed 及按档位的价格键）。
值：Adjust Dashboard 里配置的事件 token（字符串）。
未配置的键在调用 SkinConfig.trackAdjustEvent 时不会上报。示例仅展示 register / purchase；完整业务档位名需与 AnalyticsEvents 中约定一致。
11. extConfig
描述 common_info 返回里 extConfig JSON 如何解析为 ExtConfigData，以及本地默认值如何与线上下发合并。
11.1 keys
各业务语义对应线网上可能出现的键名列表（按顺序取第一个存在的键），用于兼容多版本后端键名。示例：
showVideoMenu：如go_run、need_wait— 控制是否展示视频首页顶栏等（需为布尔或可解析为布尔）。forbidScreenshot/blockScreenshot：截屏相关策略。allowThirdPartyPayment：第三方支付开关。privacyUrl/agreementUrl：链接类字段。items：运营卡片数组所在键名。
11.2 itemKeys
列表项逻辑字段（如 image、title、videoUrl）到线网键名列表的映射；解析 items 数组中每一项时使用。详见 ExtConfigKeySchema 类注释。
11.3 itemKeysHome / itemKeysTask
可选。同一逻辑名在首页展示与创建任务场景可映射到不同线网键；未配置时回退到 itemKeys。
11.4 taskItemMapping
将 extConfig.items 中单项组装成与 GET /v1/image/img2video/tasks 单项在 fieldMapping 之后同形的结构，以便走 TaskItem.fromJson。
键：目标路径（点号嵌套，如 previewVideo.url）。
值：源对象上按顺序尝试的源路径列表。
11.5 itemsApplyFieldMappingBeforeTaskMapping
true（默认）：先对单项做fieldMapping.mapResponse，再按taskItemMapping取值。false：在原始线网单项上按源路径取值。
11.6 defaultItemTitle
extConfig.items 解析后标题仍为空时填入的占位字符串（对应代码中的 defaultItemTitleWhenEmpty）。
11.7 defaults
线网键名 → 默认值，与 common_info 返回的 extConfig 对象 浅合并：服务器非 null 的顶层键覆盖本地。用于本地兜底 URL、默认开关、空 items 等。合并逻辑见 SkinExtConfigSection.mergeDefaults。
12. 相关入口
- 初始化：
ClientBootstrap.initFromAsset（client_bootstrap.dart） - 配置模型：
SkinConfig（skin_config.dart） - 创建新换皮应用步骤：create_new_skin_app.md