docs: add Status Page Widget guide

docs.json

@@ -176,6 +176,7 @@
                   "zh/on-call/statuspage/statuspage",
                   "zh/on-call/statuspage/get-started",
                   "zh/on-call/statuspage/create-manage-page",
+                  "zh/on-call/statuspage/widgets",
                   "zh/on-call/statuspage/components-sections",
                   "zh/on-call/statuspage/publish-events",
                   "zh/on-call/statuspage/templates",
@@ -1385,6 +1386,7 @@
                   "en/on-call/statuspage/statuspage",
                   "en/on-call/statuspage/get-started",
                   "en/on-call/statuspage/create-manage-page",
+                  "en/on-call/statuspage/widgets",
                   "en/on-call/statuspage/components-sections",
                   "en/on-call/statuspage/publish-events",
                   "en/on-call/statuspage/templates",
@@ -2477,4 +2479,4 @@
       "href": "https://console.flashcat.cloud"
     }
   }
-}
+}

en/on-call/statuspage/widgets.mdx

@@ -0,0 +1,155 @@
+---
+title: "Embed status widgets"
+description: "Display status page data in your website or app with a badge, banner, or public JSON API"
+---
+
+Public status pages provide three ways to embed status information: an always-visible status badge, an event-driven status banner, and a status summary API for custom integrations.
+
+In the Flashduty console, go to **Status Pages → select a public page → Widget** to preview a widget and copy the code for the current configuration.
+
+<Note>
+Widgets and the status summary API are available for public status pages only. They do not identify visitors and do not require an APP Key.
+</Note>
+
+## Status badge
+
+The badge always shows the current overall status. It works well in a website footer, help center, or console navigation. You can choose its theme, language, and size.
+
+Paste the script and `<flashduty-status-widget>` element generated by the console into your HTML:
+
+```html
+<script
+  async
+  src="https://statuspage.flashcat.cloud/status-page-widget/1.0.0/widget.js"
+  integrity="sha384-rHeDWu6t1L4HVGFp/l/qBEogwjGqG64sKN2Sy1GzX10y49EOrKISEREQYGS2BBRW"
+  crossorigin="anonymous">
+</script>
+
+<flashduty-status-widget
+  page="https://status.example.com"
+  type="badge"
+  theme="auto"
+  locale="en"
+  size="medium">
+</flashduty-status-widget>
+```
+
+Prefer the complete snippet generated by the console. The script URL is versioned, and its matching `integrity` value remains stable for that version.
+
+## Status banner
+
+The banner actively communicates incidents and maintenance:
+
+- It shows the event title and a details link during an incident or maintenance; it includes the latest public update when available, otherwise the current phase or start time
+- Scheduled maintenance appears automatically during the 24 hours before it starts
+- It takes up no space when there is no active event or upcoming maintenance
+- With multiple incidents, it shows the highest-impact incident first; when there is no incident, it shows the earliest active maintenance and indicates how many others exist
+- If a visitor dismisses an update, it stays hidden for that browser session and appears again when the event is updated
+
+```html
+<script
+  async
+  src="https://statuspage.flashcat.cloud/status-page-widget/1.0.0/widget.js"
+  integrity="sha384-rHeDWu6t1L4HVGFp/l/qBEogwjGqG64sKN2Sy1GzX10y49EOrKISEREQYGS2BBRW"
+  crossorigin="anonymous">
+</script>
+
+<flashduty-status-widget
+  page="https://status.example.com"
+  type="banner"
+  theme="auto"
+  locale="en"
+  position="top">
+</flashduty-status-widget>
+```
+
+## Status summary API
+
+If the built-in widgets do not fit your UI, read the public status summary and build your own component or server-side integration.
+
+```http
+GET {status-page-url}/api/widget/v1/summary.json
+```
+
+For example:
+
+```bash
+curl 'https://status.example.com/api/widget/v1/summary.json'
+```
+
+The endpoint is unauthenticated and supports cross-origin reads. `{status-page-url}` can be a custom status page domain or the default URL assigned by Flashduty.
+
+### Example response
+
+```json
+{
+  "schema_version": "1.0",
+  "generated_at": "2026-07-14T03:25:35Z",
+  "poll_after_seconds": 30,
+  "max_stale_seconds": 120,
+  "page": {
+    "name": "Example Status",
+    "url": "https://status.example.com"
+  },
+  "overall": {
+    "status": "partial_outage"
+  },
+  "ongoing_incidents": [
+    {
+      "id": "incident-123",
+      "title": "Some API requests are failing",
+      "phase": "investigating",
+      "impact": "partial_outage",
+      "started_at": "2026-07-14T03:07:35Z",
+      "updated_at": "2026-07-14T03:25:35Z",
+      "url": "https://status.example.com/incidents/incident-123",
+      "last_update": {
+        "at": "2026-07-14T03:25:35Z",
+        "message": "We are investigating elevated error rates."
+      },
+      "affected_components": [
+        {
+          "id": "component-api",
+          "name": "Public API",
+          "group_name": "Core services",
+          "status": "partial_outage"
+        }
+      ]
+    }
+  ],
+  "in_progress_maintenances": [],
+  "scheduled_maintenances": []
+}
+```
+
+### Response fields
+
+| Field | Description |
+| --- | --- |
+| `schema_version` | Response schema version, initially `1.0` |
+| `generated_at` | Time when the public status data last changed; remains stable while the snapshot content is unchanged |
+| `page.name` / `page.url` | Public status page name and URL |
+| `overall.status` | Overall status: `operational`, `degraded`, `partial_outage`, `full_outage`, or `maintenance` |
+| `ongoing_incidents` | Incidents currently in progress |
+| `in_progress_maintenances` | Maintenance currently in progress |
+| `scheduled_maintenances` | Scheduled maintenance starting within 72 hours, up to three entries |
+| `id` / `title` / `phase` | Event ID, public title, and current phase |
+| `url` / `updated_at` | Event details URL and last update time |
+| `last_update` | The latest public update, or `null` if no update has been published |
+| `affected_components` | Affected components that are visible on the status page |
+| `poll_after_seconds` | Recommended minimum polling interval |
+| `max_stale_seconds` | Treat the snapshot as stale if it cannot be refreshed within this period |
+
+Incident objects use `started_at` and `impact`. Maintenance objects use `starts_at`, `ends_at`, and `overdue`. A component includes `group_name` only when it belongs to a group. All three event arrays remain present when empty. All timestamps use ISO 8601.
+
+### Caching and errors
+
+- Responses include `Cache-Control` and `ETag`; send `If-None-Match` to receive `304 Not Modified`
+- In a browser, do not poll more frequently than `poll_after_seconds`
+- For high-traffic sites, proxy and cache the response through your own backend
+- The endpoint returns `404` when the page does not exist, is not public, or the deployment does not provide the Widget API
+- It returns `503` when the upstream status data is temporarily unavailable
+
+<Warning>
+Do not use the status summary API as a monitoring or alerting endpoint. It reflects information already published to the public status page and does not replace your internal monitoring system.
+</Warning>

zh/on-call/statuspage/widgets.mdx

@@ -0,0 +1,155 @@
+---
+title: "嵌入状态组件"
+description: "使用 Badge、Banner 或公开 JSON API，把状态页信息展示在你的网站和应用中"
+---
+
+公开状态页提供三种嵌入方式：常驻的状态徽标（Badge）、发生事件时出现的状态横幅（Banner），以及供自定义集成使用的状态摘要 API。
+
+在 Flashduty 控制台进入 **状态页 → 选择公开状态页 → 嵌入组件**，即可预览组件并复制当前配置对应的代码。
+
+<Note>
+嵌入组件和状态摘要 API 仅适用于公开状态页。它们不会读取访客身份，也不会要求 APP Key。
+</Note>
+
+## 状态徽标
+
+状态徽标始终显示当前整体状态，适合放在网站页脚、帮助中心或控制台导航中。你可以选择主题、语言和尺寸。
+
+将控制台生成的脚本和 `<flashduty-status-widget>` 元素粘贴到网页的 HTML 中：
+
+```html
+<script
+  async
+  src="https://statuspage.flashcat.cloud/status-page-widget/1.0.0/widget.js"
+  integrity="sha384-rHeDWu6t1L4HVGFp/l/qBEogwjGqG64sKN2Sy1GzX10y49EOrKISEREQYGS2BBRW"
+  crossorigin="anonymous">
+</script>
+
+<flashduty-status-widget
+  page="https://status.example.com"
+  type="badge"
+  theme="auto"
+  locale="zh"
+  size="medium">
+</flashduty-status-widget>
+```
+
+请优先使用控制台生成的完整代码。脚本地址带有固定版本号，对应的 `integrity` 值也不会随意变化。
+
+## 状态横幅
+
+状态横幅用于主动提示故障和维护：
+
+- 有进行中的故障或维护时显示事件标题和详情入口；存在公开更新时显示最新更新，否则显示当前阶段或开始时间
+- 计划维护在开始前 24 小时自动显示
+- 没有活动事件或近期维护时不占用页面空间
+- 同时存在多条故障时优先展示影响最严重的一条；没有故障时展示最早开始的进行中维护，并提示其余事件数量
+- 访客关闭某条更新后，本次浏览会话中不再显示；事件有新更新后会再次出现
+
+```html
+<script
+  async
+  src="https://statuspage.flashcat.cloud/status-page-widget/1.0.0/widget.js"
+  integrity="sha384-rHeDWu6t1L4HVGFp/l/qBEogwjGqG64sKN2Sy1GzX10y49EOrKISEREQYGS2BBRW"
+  crossorigin="anonymous">
+</script>
+
+<flashduty-status-widget
+  page="https://status.example.com"
+  type="banner"
+  theme="auto"
+  locale="zh"
+  position="top">
+</flashduty-status-widget>
+```
+
+## 状态摘要 API
+
+如果内置组件不能满足你的展示需求，可以读取公开状态页的状态摘要，自行实现组件或服务端集成。
+
+```http
+GET {状态页地址}/api/widget/v1/summary.json
+```
+
+例如：
+
+```bash
+curl 'https://status.example.com/api/widget/v1/summary.json'
+```
+
+接口无需鉴权，并允许跨域读取。`{状态页地址}` 可以是状态页的自定义域名，也可以是 Flashduty 分配的默认地址。
+
+### 响应示例
+
+```json
+{
+  "schema_version": "1.0",
+  "generated_at": "2026-07-14T03:25:35Z",
+  "poll_after_seconds": 30,
+  "max_stale_seconds": 120,
+  "page": {
+    "name": "Example Status",
+    "url": "https://status.example.com"
+  },
+  "overall": {
+    "status": "partial_outage"
+  },
+  "ongoing_incidents": [
+    {
+      "id": "incident-123",
+      "title": "部分 API 请求失败",
+      "phase": "investigating",
+      "impact": "partial_outage",
+      "started_at": "2026-07-14T03:07:35Z",
+      "updated_at": "2026-07-14T03:25:35Z",
+      "url": "https://status.example.com/incidents/incident-123",
+      "last_update": {
+        "at": "2026-07-14T03:25:35Z",
+        "message": "我们正在排查错误率上升的问题。"
+      },
+      "affected_components": [
+        {
+          "id": "component-api",
+          "name": "公共 API",
+          "group_name": "核心服务",
+          "status": "partial_outage"
+        }
+      ]
+    }
+  ],
+  "in_progress_maintenances": [],
+  "scheduled_maintenances": []
+}
+```
+
+### 响应字段
+
+| 字段 | 说明 |
+| --- | --- |
+| `schema_version` | 当前响应结构版本，初始版本为 `1.0` |
+| `generated_at` | 公开状态数据最后发生变化的时间；内容不变时保持稳定 |
+| `page.name` / `page.url` | 状态页名称和公开地址 |
+| `overall.status` | 整体状态：`operational`、`degraded`、`partial_outage`、`full_outage` 或 `maintenance` |
+| `ongoing_incidents` | 当前进行中的故障 |
+| `in_progress_maintenances` | 当前进行中的维护 |
+| `scheduled_maintenances` | 未来 72 小时内的计划维护，最多三条 |
+| `id` / `title` / `phase` | 事件 ID、公开标题和当前阶段 |
+| `url` / `updated_at` | 事件详情地址和最近更新时间 |
+| `last_update` | 最近一次公开更新；尚无更新时为 `null` |
+| `affected_components` | 当前受影响且允许在状态页展示的组件 |
+| `poll_after_seconds` | 建议的最短轮询间隔 |
+| `max_stale_seconds` | 超过该时间仍未成功刷新时，应把数据视为过期 |
+
+故障对象使用 `started_at` 和 `impact`；维护对象使用 `starts_at`、`ends_at` 和 `overdue`。组件的 `group_name` 仅在组件属于分组时出现。三个事件数组即使为空也会保留。所有时间均为 ISO 8601 格式。
+
+### 缓存与错误处理
+
+- 响应携带 `Cache-Control` 和 `ETag`；请求可通过 `If-None-Match` 获取 `304 Not Modified`
+- 浏览器端最低按 `poll_after_seconds` 轮询，不要为每次页面渲染重复请求
+- 高流量网站建议由自己的服务端代理并缓存该响应
+- 状态页不存在、不是公开页，或当前部署未提供 Widget API 时返回 `404`
+- 上游状态暂时不可用时返回 `503`
+
+<Warning>
+不要把状态摘要 API 当成监控或告警接口。它反映公开状态页已经发布的内容，适合面向用户展示，不保证替代内部监控系统。
+</Warning>