From 6a570570e044c7cf759d8caa445cecde9fa85da2 Mon Sep 17 00:00:00 2001 From: debidong <1953531014@qq.com> Date: Tue, 14 Jul 2026 15:00:57 +0800 Subject: [PATCH] docs: add status page widget guide --- docs.json | 4 +- en/on-call/statuspage/widgets.mdx | 155 ++++++++++++++++++++++++++++++ zh/on-call/statuspage/widgets.mdx | 155 ++++++++++++++++++++++++++++++ 3 files changed, 313 insertions(+), 1 deletion(-) create mode 100644 en/on-call/statuspage/widgets.mdx create mode 100644 zh/on-call/statuspage/widgets.mdx diff --git a/docs.json b/docs.json index c75b2e9..f8e8633 100644 --- a/docs.json +++ b/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" } } -} \ No newline at end of file +} diff --git a/en/on-call/statuspage/widgets.mdx b/en/on-call/statuspage/widgets.mdx new file mode 100644 index 0000000..08b9fd3 --- /dev/null +++ b/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. + + +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. + + +## 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 `` element generated by the console into your HTML: + +```html + + + + +``` + +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 + + + + +``` + +## 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 + + +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. + diff --git a/zh/on-call/statuspage/widgets.mdx b/zh/on-call/statuspage/widgets.mdx new file mode 100644 index 0000000..db0e617 --- /dev/null +++ b/zh/on-call/statuspage/widgets.mdx @@ -0,0 +1,155 @@ +--- +title: "嵌入状态组件" +description: "使用 Badge、Banner 或公开 JSON API，把状态页信息展示在你的网站和应用中" +--- + +公开状态页提供三种嵌入方式：常驻的状态徽标（Badge）、发生事件时出现的状态横幅（Banner），以及供自定义集成使用的状态摘要 API。 + +在 Flashduty 控制台进入 **状态页 → 选择公开状态页 → 嵌入组件**，即可预览组件并复制当前配置对应的代码。 + + +嵌入组件和状态摘要 API 仅适用于公开状态页。它们不会读取访客身份，也不会要求 APP Key。 + + +## 状态徽标 + +状态徽标始终显示当前整体状态，适合放在网站页脚、帮助中心或控制台导航中。你可以选择主题、语言和尺寸。 + +将控制台生成的脚本和 `` 元素粘贴到网页的 HTML 中： + +```html + + + + +``` + +请优先使用控制台生成的完整代码。脚本地址带有固定版本号，对应的 `integrity` 值也不会随意变化。 + +## 状态横幅 + +状态横幅用于主动提示故障和维护： + +- 有进行中的故障或维护时显示事件标题和详情入口；存在公开更新时显示最新更新，否则显示当前阶段或开始时间 +- 计划维护在开始前 24 小时自动显示 +- 没有活动事件或近期维护时不占用页面空间 +- 同时存在多条故障时优先展示影响最严重的一条；没有故障时展示最早开始的进行中维护，并提示其余事件数量 +- 访客关闭某条更新后，本次浏览会话中不再显示；事件有新更新后会再次出现 + +```html + + + + +``` + +## 状态摘要 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` + + +不要把状态摘要 API 当成监控或告警接口。它反映公开状态页已经发布的内容，适合面向用户展示，不保证替代内部监控系统。 +