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" } }'

10가지 위젯 템플릿

데이터에 맞는 레이아웃을 고르세요. 단일 값, 진행 막대, 상태 표시등, 게이지, 통계 목록, 추세 스파크라인, 카운트다운, 배터리 잔량, 일정, 엔드포인트 간 흐름. 모든 템플릿은 PushWard 앱이 네이티브로 렌더링하므로, 디자인 작업 없이도 데이터가 다듬어진 레이아웃에 담깁니다.

위젯 템플릿 살펴보기 →

동작하는 인터랙티브 위젯

위젯에는 최대 세 개의 탭 동작을 담을 수 있습니다. 홈 화면을 떠나지 않고 조용한 웹훅을 발사하거나, 다른 앱으로 딥 링크하거나, URL을 열 수 있습니다. 서버 재시작, 단축어 실행, 알림 확인을 위젯에서 바로 — PushWard 앱은 한 번도 열릴 필요가 없습니다.

여러분의 스택과 함께

이미 운영 중인 도구로 위젯에 데이터를 공급하세요. Grafana 경고가 상태 표시등을 바꾸고, Home Assistant 자동화가 온도를 업데이트하고, GitHub Actions 작업이 배포 카운터를 올리고, cron 스크립트가 백업 경과 시간을 게시합니다. HTTP 요청을 보낼 수 있다면 위젯 하나를 가질 수 있습니다.

모든 통합 보기 →

위젯과 실시간 현황을 함께

위젯과 실시간 현황은 상호 보완적입니다. 위젯은 제거할 때까지 홈 화면에 남는 지속적이고 은은한 상태 표시이고, 실시간 현황은 시작과 끝이 있는 작업으로 실행되는 동안 잠금 화면과 Dynamic Island에 고정됩니다. 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로 첫 위젯을 등록해 보세요.