跳至內容

為一切會說 HTTP 的事物打造的 iOS 小工具 API

PushWard 是一個面向 Apple iOS 小工具的 API：宣告一次小工具，然後用簡單的 HTTP 請求驅動 iPhone 的主畫面、鎖定畫面與待機模式。每次更新都會觸發一次推播驅動的 WidgetKit 重新整理 — 無需輪詢、無需 WidgetKit 程式碼、無需 Xcode，您這邊也無需 App Store 審查。

什麼是 iOS 主畫面小工具？

小工具是 Apple 的一目了然式顯示面：iPhone 主畫面、鎖定畫面與待機模式中始終可見的小方塊，無需開啟應用程式即可顯示資訊。它們以 Apple 的裝置端框架 WidgetKit 打造，通常每一個都隸屬於一款您必須親自建置、簽署並發佈的應用程式。PushWard 的小工具不同：由 PushWard 應用程式繪製，內容來自您的 API 呼叫 — 感測器讀數、伺服器健康檢查、部署計數器，任何能以 JSON 傳送的資料。

API 的運作方式

用 POST 註冊一個小工具，再用 PATCH 更新它 — 整個循環就是如此。每次更新都會透過 Apple Push Notification service 傳送一個輕量推播，通知 WidgetKit 重新載入小工具的時間軸，新值無需小工具輪詢就會出現。可選的逐小工具推播節流會把突發的資料來源合併處理。

透過 HTTP 註冊並更新小工具 
# 1. Register a widget
curl -X POST https://api.pushward.app/widgets \
  -H "Authorization: Bearer hlk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "slug": "cpu-load", "name": "CPU Load", "content": {
    "template": "progress", "value": 0.42,
    "label": "load avg", "icon": "cpu", "accent_color": "cyan"
  } }'

# 2. Update it - WidgetKit refreshes the widget
curl -X PATCH https://api.pushward.app/widgets/cpu-load \
  -H "Authorization: Bearer hlk_YOUR_KEY" \
  -H "Content-Type: application/merge-patch+json" \
  -d '{ "content": { "value": 0.78, "accent_color": "orange" } }'

十種小工具範本

選擇契合資料的版面：單一數值、進度列、狀態指示燈、儀表、統計清單、趨勢迷你圖、倒數計時、電池電量、行程或端點之間的流向。每個範本都由 PushWard 應用程式原生繪製，您的資料無需任何設計工作就能落入精緻的版面。

趨勢小工具 — 上升的青色迷你圖上方顯示 p95 延遲 371 ms，帶向上箭頭以及重新整理和歷史記錄按鈕。
電池小工具 — 四個綠色充電圓環，分別顯示 68%、帶充電閃電的 45%、紅色的 18% 和 92%。
流向小工具 — 電力：太陽能 3,200 W，電網 1,400 W 帶流出箭頭，電池 800 W 帶流入充電箭頭，家庭用電 1,000 W。

瀏覽小工具範本 →

能採取行動的互動式小工具

小工具最多可攜帶三個點按操作：不離開主畫面就觸發靜默 webhook、深層連結到另一個應用程式，或開啟一個 URL。直接在小工具上重新啟動伺服器、觸發捷徑或確認警報 — PushWard 應用程式完全不必開啟。

與您的技術棧協作

用您已在執行的工具為小工具供給資料：Grafana 警報切換狀態指示燈，Home Assistant 自動化更新溫度，GitHub Actions 工作遞增部署計數器，cron 指令碼回報備份的時間。只要能傳送 HTTP 請求，就能擁有一個小工具。

查看所有整合 →

小工具與即時動態並用

小工具與即時動態互為補充：小工具是持久的環境化狀態，會一直留在主畫面上直到被移除；即時動態則是一個有始有終的任務，執行期間固定在鎖定畫面與動態島上。PushWard 透過同一個 REST API 和同一個整合金鑰驅動兩者。

了解即時動態 API →

常見問題

這是 Apple 官方的 WidgetKit API 嗎？

不是。WidgetKit 是 Apple 的裝置端框架，直接使用它意味著建置並發佈內含小工具延伸功能的自有 iOS 應用程式。PushWard 是一個獨立的 iOS 小工具 API：PushWard 應用程式內建 WidgetKit 延伸功能，您的 HTTP 請求決定它顯示什麼。

小工具的更新有多快？

每個 PATCH 都會觸發一個輕量推播，通知 WidgetKit 重新載入小工具，因此更新通常在幾秒內生效。逐小工具的推播節流（1 秒到 1 小時）會合併突發的資料來源，讓重新整理維持在 iOS 授予延伸功能的預算之內。

小工具能在鎖定畫面與待機模式中使用嗎？

能。PushWard 小工具可以加入 iPhone 的主畫面、鎖定畫面與待機模式。鎖定畫面的精簡配件欄位會繪製濃縮版面，點按即可開啟設定好的點按操作。

接收者需要安裝應用程式嗎？

需要 — 免費的 PushWard iOS 應用程式（iOS 26 或以上版本）負責繪製小工具，並將它們註冊到 iOS 小工具選擇器中。您無需建置或向 App Store 提交任何東西。

試用 iOS 小工具 API

在 playground 中組合小工具承載內容，觀看它在模擬 iPhone 上繪製，或閱讀入門指南，幾分鐘內用 curl 註冊您的第一個小工具。

Playground 小工具 小工具 API 即時動態