API Widget trên iOS cho mọi thứ biết nói HTTP
PushWard là một API cho widget iOS của Apple: khai báo widget một lần, rồi điều khiển Màn hình chính, Màn hình khóa và Chế độ chờ của iPhone bằng những yêu cầu HTTP đơn giản. Mỗi lần cập nhật kích hoạt một lần làm mới WidgetKit theo push — không polling, không mã WidgetKit, không Xcode, không phải qua xét duyệt App Store từ phía bạn.
Widget Màn hình chính iOS là gì?
Widget là những bề mặt xem nhanh của Apple: các ô nhỏ luôn hiển thị trên Màn hình chính, Màn hình khóa và Chế độ chờ của iPhone, cho thấy thông tin mà không cần mở ứng dụng. Chúng được xây dựng bằng WidgetKit, framework chạy trên thiết bị của Apple, và thông thường mỗi widget thuộc về một ứng dụng mà bạn phải tự xây dựng, ký và phát hành. Widget của PushWard thì khác: ứng dụng PushWard hiển thị chúng, còn nội dung đến từ các lời gọi API của bạn — một số đo cảm biến, một lần kiểm tra sức khỏe máy chủ, một bộ đếm lượt triển khai, bất cứ thứ gì có thể gửi dưới dạng JSON.
API hoạt động thế nào
Đăng ký widget bằng POST, rồi cập nhật bằng PATCH — vòng lặp chỉ có vậy. Mỗi lần cập nhật gửi một push gọn nhẹ qua Apple Push Notification service, báo WidgetKit tải lại dòng thời gian của widget, nên giá trị mới xuất hiện mà widget không bao giờ phải polling. Bộ tiết lưu push tùy chọn theo từng widget sẽ gộp các nguồn gửi dồn dập.
# 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" } }'Mười mẫu widget
Chọn bố cục hợp với dữ liệu: một giá trị đơn, thanh tiến trình, đèn trạng thái, đồng hồ đo, danh sách thống kê, biểu đồ xu hướng mini, đếm ngược, mức pin, lịch trình, hay dòng chảy giữa các điểm. Mọi mẫu đều được ứng dụng PushWard hiển thị nguyên bản, nên dữ liệu của bạn nằm gọn trong một bố cục chỉn chu mà không tốn chút công thiết kế nào.
Widget tương tác biết hành động
Widget có thể mang tối đa ba hành động chạm: kích hoạt một webhook thầm lặng mà không rời Màn hình chính, liên kết sâu sang ứng dụng khác, hoặc mở một URL. Khởi động lại máy chủ, chạy một Phím tắt, hay xác nhận cảnh báo ngay từ widget — ứng dụng PushWard không bao giờ cần mở ra.
Hoạt động với hệ công cụ của bạn
Cấp dữ liệu cho widget từ những công cụ bạn đang chạy sẵn: cảnh báo Grafana đảo đèn trạng thái, tự động hóa Home Assistant cập nhật nhiệt độ, job GitHub Actions tăng bộ đếm triển khai, tập lệnh cron báo tuổi bản sao lưu. Chỉ cần gửi được yêu cầu HTTP là có thể sở hữu một widget.
Widget và Hoạt động trực tiếp song hành
Widget và Hoạt động trực tiếp bổ trợ cho nhau: widget là trạng thái bền bỉ, lặng lẽ, ở lại Màn hình chính cho đến khi bị gỡ, còn Hoạt động trực tiếp là một nhiệm vụ có mở đầu và kết thúc, tự ghim vào Màn hình khóa và Dynamic Island trong lúc chạy. PushWard điều khiển cả hai qua cùng một REST API và cùng một khóa tích hợp.
Tìm hiểu API Hoạt động trực tiếp →
Câu hỏi thường gặp
Đây có phải là API WidgetKit chính thức của Apple không?
Không. WidgetKit là framework chạy trên thiết bị của Apple, và dùng nó trực tiếp nghĩa là phải xây dựng rồi phát hành ứng dụng iOS của riêng bạn kèm phần mở rộng widget. PushWard là một API widget trên iOS độc lập: ứng dụng PushWard mang sẵn phần mở rộng WidgetKit, còn các yêu cầu HTTP của bạn quyết định nó hiển thị gì.
Widget cập nhật nhanh đến mức nào?
Mỗi PATCH kích hoạt một push gọn nhẹ báo WidgetKit tải lại widget, nên bản cập nhật thường đến trong vài giây. Bộ tiết lưu push theo từng widget (từ 1 giây đến 1 giờ) gộp các nguồn gửi dồn dập, giữ số lần làm mới trong hạn mức mà iOS cấp cho phần mở rộng.
Widget có hoạt động trên Màn hình khóa và trong Chế độ chờ không?
Có. Widget của PushWard có thể được thêm vào Màn hình chính, Màn hình khóa và Chế độ chờ của iPhone. Các ô phụ kiện thu gọn trên Màn hình khóa hiển thị bố cục cô đọng, và chạm vào một ô sẽ mở hành động chạm đã cấu hình.
Người nhận có cần cài ứng dụng không?
Có — ứng dụng iOS miễn phí PushWard (iOS 26 trở lên) hiển thị các widget và đăng ký chúng vào trình chọn widget của iOS. Bạn không phải xây dựng hay nộp gì lên App Store.
Dùng thử API Widget trên iOS
Dựng payload widget trong playground và xem nó hiển thị trên iPhone mô phỏng, hoặc đọc hướng dẫn bắt đầu và đăng ký widget đầu tiên của bạn bằng curl trong vài phút.