Skip to content

Commit 6a57057

Browse files
debidongdebidong
committed
docs: add status page widget guide
1 parent 3776354 commit 6a57057

3 files changed

Lines changed: 313 additions & 1 deletion

File tree

‎docs.json‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -176,6 +176,7 @@
176176
"zh/on-call/statuspage/statuspage",
177177
"zh/on-call/statuspage/get-started",
178178
"zh/on-call/statuspage/create-manage-page",
179+
"zh/on-call/statuspage/widgets",
179180
"zh/on-call/statuspage/components-sections",
180181
"zh/on-call/statuspage/publish-events",
181182
"zh/on-call/statuspage/templates",
@@ -1385,6 +1386,7 @@
13851386
"en/on-call/statuspage/statuspage",
13861387
"en/on-call/statuspage/get-started",
13871388
"en/on-call/statuspage/create-manage-page",
1389+
"en/on-call/statuspage/widgets",
13881390
"en/on-call/statuspage/components-sections",
13891391
"en/on-call/statuspage/publish-events",
13901392
"en/on-call/statuspage/templates",
@@ -2477,4 +2479,4 @@
24772479
"href": "https://console.flashcat.cloud"
24782480
}
24792481
}
2480-
}
2482+
}

‎en/on-call/statuspage/widgets.mdx‎

Lines changed: 155 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,155 @@
1+
---
2+
title: "Embed status widgets"
3+
description: "Display status page data in your website or app with a badge, banner, or public JSON API"
4+
---
5+
6+
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.
7+
8+
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.
9+
10+
<Note>
11+
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.
12+
</Note>
13+
14+
## Status badge
15+
16+
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.
17+
18+
Paste the script and `<flashduty-status-widget>` element generated by the console into your HTML:
19+
20+
```html
21+
<script
22+
async
23+
src="https://statuspage.flashcat.cloud/status-page-widget/1.0.0/widget.js"
24+
integrity="sha384-rHeDWu6t1L4HVGFp/l/qBEogwjGqG64sKN2Sy1GzX10y49EOrKISEREQYGS2BBRW"
25+
crossorigin="anonymous">
26+
</script>
27+
28+
<flashduty-status-widget
29+
page="https://status.example.com"
30+
type="badge"
31+
theme="auto"
32+
locale="en"
33+
size="medium">
34+
</flashduty-status-widget>
35+
```
36+
37+
Prefer the complete snippet generated by the console. The script URL is versioned, and its matching `integrity` value remains stable for that version.
38+
39+
## Status banner
40+
41+
The banner actively communicates incidents and maintenance:
42+
43+
- 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
44+
- Scheduled maintenance appears automatically during the 24 hours before it starts
45+
- It takes up no space when there is no active event or upcoming maintenance
46+
- 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
47+
- If a visitor dismisses an update, it stays hidden for that browser session and appears again when the event is updated
48+
49+
```html
50+
<script
51+
async
52+
src="https://statuspage.flashcat.cloud/status-page-widget/1.0.0/widget.js"
53+
integrity="sha384-rHeDWu6t1L4HVGFp/l/qBEogwjGqG64sKN2Sy1GzX10y49EOrKISEREQYGS2BBRW"
54+
crossorigin="anonymous">
55+
</script>
56+
57+
<flashduty-status-widget
58+
page="https://status.example.com"
59+
type="banner"
60+
theme="auto"
61+
locale="en"
62+
position="top">
63+
</flashduty-status-widget>
64+
```
65+
66+
## Status summary API
67+
68+
If the built-in widgets do not fit your UI, read the public status summary and build your own component or server-side integration.
69+
70+
```http
71+
GET {status-page-url}/api/widget/v1/summary.json
72+
```
73+
74+
For example:
75+
76+
```bash
77+
curl 'https://status.example.com/api/widget/v1/summary.json'
78+
```
79+
80+
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.
81+
82+
### Example response
83+
84+
```json
85+
{
86+
"schema_version": "1.0",
87+
"generated_at": "2026-07-14T03:25:35Z",
88+
"poll_after_seconds": 30,
89+
"max_stale_seconds": 120,
90+
"page": {
91+
"name": "Example Status",
92+
"url": "https://status.example.com"
93+
},
94+
"overall": {
95+
"status": "partial_outage"
96+
},
97+
"ongoing_incidents": [
98+
{
99+
"id": "incident-123",
100+
"title": "Some API requests are failing",
101+
"phase": "investigating",
102+
"impact": "partial_outage",
103+
"started_at": "2026-07-14T03:07:35Z",
104+
"updated_at": "2026-07-14T03:25:35Z",
105+
"url": "https://status.example.com/incidents/incident-123",
106+
"last_update": {
107+
"at": "2026-07-14T03:25:35Z",
108+
"message": "We are investigating elevated error rates."
109+
},
110+
"affected_components": [
111+
{
112+
"id": "component-api",
113+
"name": "Public API",
114+
"group_name": "Core services",
115+
"status": "partial_outage"
116+
}
117+
]
118+
}
119+
],
120+
"in_progress_maintenances": [],
121+
"scheduled_maintenances": []
122+
}
123+
```
124+
125+
### Response fields
126+
127+
| Field | Description |
128+
| --- | --- |
129+
| `schema_version` | Response schema version, initially `1.0` |
130+
| `generated_at` | Time when the public status data last changed; remains stable while the snapshot content is unchanged |
131+
| `page.name` / `page.url` | Public status page name and URL |
132+
| `overall.status` | Overall status: `operational`, `degraded`, `partial_outage`, `full_outage`, or `maintenance` |
133+
| `ongoing_incidents` | Incidents currently in progress |
134+
| `in_progress_maintenances` | Maintenance currently in progress |
135+
| `scheduled_maintenances` | Scheduled maintenance starting within 72 hours, up to three entries |
136+
| `id` / `title` / `phase` | Event ID, public title, and current phase |
137+
| `url` / `updated_at` | Event details URL and last update time |
138+
| `last_update` | The latest public update, or `null` if no update has been published |
139+
| `affected_components` | Affected components that are visible on the status page |
140+
| `poll_after_seconds` | Recommended minimum polling interval |
141+
| `max_stale_seconds` | Treat the snapshot as stale if it cannot be refreshed within this period |
142+
143+
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.
144+
145+
### Caching and errors
146+
147+
- Responses include `Cache-Control` and `ETag`; send `If-None-Match` to receive `304 Not Modified`
148+
- In a browser, do not poll more frequently than `poll_after_seconds`
149+
- For high-traffic sites, proxy and cache the response through your own backend
150+
- The endpoint returns `404` when the page does not exist, is not public, or the deployment does not provide the Widget API
151+
- It returns `503` when the upstream status data is temporarily unavailable
152+
153+
<Warning>
154+
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.
155+
</Warning>

‎zh/on-call/statuspage/widgets.mdx‎

Lines changed: 155 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,155 @@
1+
---
2+
title: "嵌入状态组件"
3+
description: "使用 Badge、Banner 或公开 JSON API，把状态页信息展示在你的网站和应用中"
4+
---
5+
6+
公开状态页提供三种嵌入方式：常驻的状态徽标（Badge）、发生事件时出现的状态横幅（Banner），以及供自定义集成使用的状态摘要 API。
7+
8+
在 Flashduty 控制台进入 **状态页 → 选择公开状态页 → 嵌入组件**，即可预览组件并复制当前配置对应的代码。
9+
10+
<Note>
11+
嵌入组件和状态摘要 API 仅适用于公开状态页。它们不会读取访客身份，也不会要求 APP Key。
12+
</Note>
13+
14+
## 状态徽标
15+
16+
状态徽标始终显示当前整体状态，适合放在网站页脚、帮助中心或控制台导航中。你可以选择主题、语言和尺寸。
17+
18+
将控制台生成的脚本和 `<flashduty-status-widget>` 元素粘贴到网页的 HTML 中：
19+
20+
```html
21+
<script
22+
async
23+
src="https://statuspage.flashcat.cloud/status-page-widget/1.0.0/widget.js"
24+
integrity="sha384-rHeDWu6t1L4HVGFp/l/qBEogwjGqG64sKN2Sy1GzX10y49EOrKISEREQYGS2BBRW"
25+
crossorigin="anonymous">
26+
</script>
27+
28+
<flashduty-status-widget
29+
page="https://status.example.com"
30+
type="badge"
31+
theme="auto"
32+
locale="zh"
33+
size="medium">
34+
</flashduty-status-widget>
35+
```
36+
37+
请优先使用控制台生成的完整代码。脚本地址带有固定版本号，对应的 `integrity` 值也不会随意变化。
38+
39+
## 状态横幅
40+
41+
状态横幅用于主动提示故障和维护：
42+
43+
- 有进行中的故障或维护时显示事件标题和详情入口；存在公开更新时显示最新更新，否则显示当前阶段或开始时间
44+
- 计划维护在开始前 24 小时自动显示
45+
- 没有活动事件或近期维护时不占用页面空间
46+
- 同时存在多条故障时优先展示影响最严重的一条；没有故障时展示最早开始的进行中维护，并提示其余事件数量
47+
- 访客关闭某条更新后，本次浏览会话中不再显示；事件有新更新后会再次出现
48+
49+
```html
50+
<script
51+
async
52+
src="https://statuspage.flashcat.cloud/status-page-widget/1.0.0/widget.js"
53+
integrity="sha384-rHeDWu6t1L4HVGFp/l/qBEogwjGqG64sKN2Sy1GzX10y49EOrKISEREQYGS2BBRW"
54+
crossorigin="anonymous">
55+
</script>
56+
57+
<flashduty-status-widget
58+
page="https://status.example.com"
59+
type="banner"
60+
theme="auto"
61+
locale="zh"
62+
position="top">
63+
</flashduty-status-widget>
64+
```
65+
66+
## 状态摘要 API
67+
68+
如果内置组件不能满足你的展示需求，可以读取公开状态页的状态摘要，自行实现组件或服务端集成。
69+
70+
```http
71+
GET {状态页地址}/api/widget/v1/summary.json
72+
```
73+
74+
例如：
75+
76+
```bash
77+
curl 'https://status.example.com/api/widget/v1/summary.json'
78+
```
79+
80+
接口无需鉴权，并允许跨域读取。`{状态页地址}` 可以是状态页的自定义域名，也可以是 Flashduty 分配的默认地址。
81+
82+
### 响应示例
83+
84+
```json
85+
{
86+
"schema_version": "1.0",
87+
"generated_at": "2026-07-14T03:25:35Z",
88+
"poll_after_seconds": 30,
89+
"max_stale_seconds": 120,
90+
"page": {
91+
"name": "Example Status",
92+
"url": "https://status.example.com"
93+
},
94+
"overall": {
95+
"status": "partial_outage"
96+
},
97+
"ongoing_incidents": [
98+
{
99+
"id": "incident-123",
100+
"title": "部分 API 请求失败",
101+
"phase": "investigating",
102+
"impact": "partial_outage",
103+
"started_at": "2026-07-14T03:07:35Z",
104+
"updated_at": "2026-07-14T03:25:35Z",
105+
"url": "https://status.example.com/incidents/incident-123",
106+
"last_update": {
107+
"at": "2026-07-14T03:25:35Z",
108+
"message": "我们正在排查错误率上升的问题。"
109+
},
110+
"affected_components": [
111+
{
112+
"id": "component-api",
113+
"name": "公共 API",
114+
"group_name": "核心服务",
115+
"status": "partial_outage"
116+
}
117+
]
118+
}
119+
],
120+
"in_progress_maintenances": [],
121+
"scheduled_maintenances": []
122+
}
123+
```
124+
125+
### 响应字段
126+
127+
| 字段 | 说明 |
128+
| --- | --- |
129+
| `schema_version` | 当前响应结构版本，初始版本为 `1.0` |
130+
| `generated_at` | 公开状态数据最后发生变化的时间；内容不变时保持稳定 |
131+
| `page.name` / `page.url` | 状态页名称和公开地址 |
132+
| `overall.status` | 整体状态：`operational`、`degraded`、`partial_outage`、`full_outage` 或 `maintenance` |
133+
| `ongoing_incidents` | 当前进行中的故障 |
134+
| `in_progress_maintenances` | 当前进行中的维护 |
135+
| `scheduled_maintenances` | 未来 72 小时内的计划维护，最多三条 |
136+
| `id` / `title` / `phase` | 事件 ID、公开标题和当前阶段 |
137+
| `url` / `updated_at` | 事件详情地址和最近更新时间 |
138+
| `last_update` | 最近一次公开更新；尚无更新时为 `null` |
139+
| `affected_components` | 当前受影响且允许在状态页展示的组件 |
140+
| `poll_after_seconds` | 建议的最短轮询间隔 |
141+
| `max_stale_seconds` | 超过该时间仍未成功刷新时，应把数据视为过期 |
142+
143+
故障对象使用 `started_at` 和 `impact`；维护对象使用 `starts_at`、`ends_at` 和 `overdue`。组件的 `group_name` 仅在组件属于分组时出现。三个事件数组即使为空也会保留。所有时间均为 ISO 8601 格式。
144+
145+
### 缓存与错误处理
146+
147+
- 响应携带 `Cache-Control` 和 `ETag`；请求可通过 `If-None-Match` 获取 `304 Not Modified`
148+
- 浏览器端最低按 `poll_after_seconds` 轮询，不要为每次页面渲染重复请求
149+
- 高流量网站建议由自己的服务端代理并缓存该响应
150+
- 状态页不存在、不是公开页，或当前部署未提供 Widget API 时返回 `404`
151+
- 上游状态暂时不可用时返回 `503`
152+
153+
<Warning>
154+
不要把状态摘要 API 当成监控或告警接口。它反映公开状态页已经发布的内容，适合面向用户展示，不保证替代内部监控系统。
155+
</Warning>

0 commit comments

Comments
 (0)