تخطٍّ إلى المحتوى

الأدوات

أدوات الشاشة الرئيسية وشاشة القفل ووضع الاستعداد على iOS تعمل بالدفع. صرّح عن أداة مرة واحدة، حدّث محتواها بطلب PATCH، وتتحدّث مثيلات WidgetKit لدى المستخدم تلقائيًا.

ℹ معلومة

Widgets require iOS 26 or later. On older versions the iOS app hides the widget management screen and your widgets remain dormant — the server keeps the content current so they render correctly once the user upgrades.

Widgets are persistent — once the user pins one to their Home Screen, Lock Screen, or StandBy, it stays there until they remove it. Use a widget for ambient state that should always be glanceable (a sensor reading, a server health indicator, a daily counter). For something that is currently happening and has a known end — a download, a timer, a print — reach for a Live Activity instead.

Templates

Each template is tuned for a different shape of data. Tap a card for that template's field list, worked example, and behavior notes; the shared content fields they all accept live in the API reference.

value — قيمة

رقم كبير واحد مع وحدة ووسم وسهم اتجاه اختيارية. الأمثل لقراءات المستشعرات والعدّادات.

Required: none (optional value, unit, label, trend)

Value widget — large "20" deploys count on a dark card with badges and an Up trend arrow.

progress — تقدّم

شريط تقدّم مع وسم ولون تمييز. الأمثل لنسب الاكتمال وعمليات الطرح.

Required: value 0.0 – 1.0

Progress widget — Pages 100% with a green progress bar and "10 of 10 acked".

status — حالة

كبسولة حالة برمز تعتمد على الخطورة (info و warning و critical و success). بلا أرقام — فقط الحالة.

Required: none (optional severity: info, warning, critical, success)

Status widget — Incident card with a green warning octagon and "resolved" pills.

gauge — مقياس

مقياس بإبرة بين حد أدنى وأقصى قابلين للتهيئة. الأمثل لـ SLOs وميزانيات الأخطاء والسعة.

Required: value, min_value, max_value

Gauge widget — Errors dial at 0.4% out of 5%, with MIN/MAX labels and Mute/Logs buttons.

stat_list — قائمة إحصاءات

حتى ستة صفوف وسم/قيمة. الأمثل للوحات المعلومات المدمجة — MRR / اشتراكات / تجارب، تشغيل / تعطّل / صيانة.

Required: stat_rows (array, 1 – 6 entries)

Stat list widget — On-call card with Primary, Secondary, and Time left rows.
قادم في إصدار التطبيق 1.6

يصف هذا القسم ميزة في تحديث للتطبيق قيد مراجعة App Store. يُفتح هنا تلقائيًا بمجرد أن يصبح التحديث متاحًا.

Every template accepts the shared content fields — label, subtitle, icon, the colors, and the three tap-action slots — so the styling you already use carries across. Preview any of them on the playground.

ℹ معلومة

stat_list stores up to 6 rows, but how many render depends on the placement size. By default, medium and large Home Screen widgets show all 6; the small widget shows 4, and the Lock Screen rectangular shows 3, packing rows two-up to fit up to 6 when every value is very short (a single status glyph, a small count). You can change Row Density per widget in the PushWard app: Compact packs two columns to surface up to 6 rows on any size (labels may truncate on the small placements), and Comfortable keeps a single column with larger rows (showing fewer on the smaller sizes). To see all 6 rows with full labels, use a medium or large widget, or set Compact.

How it works

  1. Your integration calls POST /widgets to declare a widget by slug, with a template and initial content.
  2. The user opens the widget picker on their device and selects your slug for any system widget family they want — small, medium, large, accessory-rectangular, accessory-circular, or accessory-inline. The same slug can appear in multiple slots.
  3. Your integration calls PATCH /widgets/{slug} whenever the underlying value changes. The server merges (RFC 7396) and pushes a thin update; the iOS widget extension reloads its timeline.
  4. If a push is missed (background fetch coalescing, no network), iOS calls back into the extension every ~30 minutes for a freshness pull — GET /widgets/{slug} always returns the latest content.

Two ways to create widgets

Widgets don't require an integration to exist. There are two paths to the same backend, and both can target the same slug — a widget created in the app can later be driven by an integration, and vice versa.

  • In the iOS app. Open the Widgets tab in PushWard, choose a template, and fill in the slug, name, and initial content. This is the right path for personal widgets — a temperature you key in by hand, a morale dial, a counter you bump from a Shortcut. The new slug appears immediately in the iOS widget picker for Home Screen, Lock Screen, and StandBy.
  • Via the HTTP API. Use this when an external service should keep the widget content current — a homelab probe, a CI job, a smart-home automation. See the API reference.

Authentication

The widgets API is reachable with an integration key (hlk_) that has the widgets flag enabled. This is the right choice for third-party integrations — toggle the flag on the key in the iOS app's integration-keys screen.

Next steps