数据概览页的所有数字都来自这一个接口:按 App、按日 / 周 / 月返回新增与活跃。本文定义请求参数、响应结构、汇总口径与降级行为,页面实现已按此约定取数。
同一域名下取数可避免跨域;页面用 credentials: "include" 携带登录态。
curl -s "https://bffmsg.fullstorynovel.com/api/stats?app=bff&dim=day" \ -H "Accept: application/json" \ --cookie "session=<sid>"
| 参数 | 类型 | 说明 | 默认 |
|---|---|---|---|
| app | string | all 或 App id(如 bff、fsn);all 返回各 App 的汇总 | all |
| dim | string | day / week / month,决定主数组的粒度与长度 | day |
| from to | date | YYYY-MM-DD,闭区间;缺省时按 dim 取最近 30 天 / 12 周 / 12 月 | — |
| tz | string | IANA 时区名,影响「今日」与自然周/月的边界 | Asia/Shanghai |
HTTP 200,application/json。三个时间数组始终同时返回,页面按 dim 取用其中之一。
{
"generatedAt": "2026-11-22T17:00:00+08:00",
"app": "bff",
"appName": "BFF Messenger",
"total": 217463, // 累计用户
"day": [
{ "label": "11-20", "new": 391, "active": 5168 },
{ "label": "11-21", "new": 468, "active": 5813 },
{ "label": "11-22", "new": 458, "active": 5743 }
],
"week": [
{ "label": "11-16~11-22", "new": 2724, "active": 11103 }
],
"month": [
{ "label": "2026-11", "new": 14650, "active": 32540 }
],
"platform": [
{ "name": "Android", "value": 63 },
{ "name": "iOS", "value": 31 },
{ "name": "Web", "value": 6 }
],
"retention": [
{ "name": "次日", "value": 40.8 },
{ "name": "3 日", "value": 29.0 },
{ "name": "7 日", "value": 17.8 },
{ "name": "30 日", "value": 9.5 }
],
"apps": [
{ "id": "bff", "name": "BFF Messenger" },
{ "id": "fsn", "name": "FullStoryNovel" }
]
}
| 字段 | 类型 | 约定 |
|---|---|---|
| generatedAt | string | ISO 8601,必须带时区偏移,用于判断数据新鲜度 |
| total | int | 累计注册用户;app=all 时为各 App 之和 |
| day[] week[] month[] | object[] | 至少 2 条才能算环比;页面绘图取末尾 12 条,明细表取末尾 10 天 / 8 周 / 8 月 |
| platform[] | object[] | {name, value},value 为百分比,合计应为 100 |
| retention[] | object[] | {name, value},value 为 0–100 的百分比 |
| apps[] | object[] | {id, name} 清单,用于渲染 App 下拉框 |
| 数组元素 | 类型 | 约定 |
|---|---|---|
| label | string | 日:MM-DD;周:MM-DD~MM-DD(周一→周日);月:YYYY-MM |
| new | int | 该周期新增注册数,≥ 0 |
| active | int | 该周期活跃数:日 = DAU、周 = WAU、月 = MAU,≥ 0 |
选择「全部 App」时,页面直接使用接口返回的 all 数据,不做二次加总,避免口径重复。
| 指标 | app = 单个 App | app = all |
|---|---|---|
| 新增 / 活跃 | 该 App 周期值 | 各 App 同期之和(新增可加;活跃按去重口径由服务端聚合) |
| 累计用户 | 该 App 累计注册 | 各 App 累计之和 |
| 平台分布 | 该 App 活跃用户占比 | 按各 App 最新一期活跃加权平均 |
| 留存 | 该 App 分档留存率 | 同上,加权平均 |
页面当前对失败的策略是「静默保留示例数据」,上线前建议按状态码给出提示。
| 状态码 | 含义 | 页面当前行为 / 建议 |
|---|---|---|
| 401 / 403 | 未登录或无权限 | 保留示例数据;建议跳转登录或显示「无权限」 |
| 404 | app 或 dim 不存在 | 忽略响应;服务端应校验 app 白名单 |
| 429 | 限流 | 保留示例数据;建议按 Retry-After 退避 |
| 5xx | 服务端异常 | 同上,并记录 trace id |
app 与 dim 必做白名单校验,其余参数可忽略。/api/stats)并沿用现有 nginx;若必须跨域,需返回 Access-Control-Allow-Origin(不可用 *)且带 Access-Control-Allow-Credentials: true。index.html 顶部 STATS_API 填成接口地址;返回真实数据后删掉头部「示例数据」徽章。// 留空 → 使用示例数据;填入后按 app + dim 取数 var STATS_API = "/api/stats";