L'API dei widget di iOS per tutto ciò che parla HTTP

Che cos'è un widget della schermata Home di iOS?

I widget sono le superfici a colpo d'occhio di Apple: piccoli riquadri sempre visibili sulla schermata Home, sulla schermata di blocco e in StandBy dell'iPhone, che mostrano informazioni senza aprire un'app. Sono costruiti con WidgetKit, il framework on-device di Apple, e di norma ognuno appartiene a un'app che dovresti costruire, firmare e pubblicare tu stesso. I widget di PushWard sono diversi: li visualizza l'app PushWard, e il loro contenuto arriva dalle tue chiamate API — la lettura di un sensore, il controllo di salute di un server, un contatore di deploy, qualsiasi cosa possa essere inviata come JSON.

Come funziona l'API

Registra un widget con una POST, poi aggiornalo con una PATCH — il ciclo è tutto qui. Ogni aggiornamento invia un push leggero tramite Apple Push Notification service che dice a WidgetKit di ricaricare la timeline del widget, così il nuovo valore appare senza che il widget faccia mai polling. Un limitatore di push opzionale per widget raggruppa le sorgenti a raffica.

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

Dieci modelli di widget

Scegli il layout adatto ai dati: un valore singolo, una barra di avanzamento, una spia di stato, un indicatore, un elenco di statistiche, una sparkline di tendenza, un conto alla rovescia, un livello di batteria, una pianificazione o un flusso tra estremi. Ogni modello è visualizzato in modo nativo dall'app PushWard, così i tuoi dati arrivano in un layout curato senza alcun lavoro di design.

Sfoglia i modelli di widget →

Widget interattivi che agiscono

I widget possono portare fino a tre azioni al tocco: lanciare un webhook silenzioso senza lasciare la schermata Home, aprire un'altra app con un link diretto, o aprire un URL. Riavvia un server, attiva un comando rapido o riconosci un avviso direttamente dal widget — l'app PushWard non deve mai aprirsi.

Funziona con il tuo stack

Alimenta i widget dagli strumenti che già usi: un avviso Grafana che cambia una spia di stato, un'automazione Home Assistant che aggiorna una temperatura, un job GitHub Actions che incrementa un contatore di deploy, uno script cron che pubblica l'età di un backup. Se può inviare una richiesta HTTP, può possedere un widget.

Vedi tutte le integrazioni →

Widget e attività in tempo reale insieme

Widget e attività in tempo reale sono complementari: un widget è uno stato persistente e ambientale che resta sulla schermata Home finché non viene rimosso, mentre un'attività in tempo reale è un compito con un inizio e una fine che si fissa alla schermata di blocco e alla Dynamic Island mentre è in corso. PushWard guida entrambi tramite la stessa REST API e la stessa chiave di integrazione.

Scopri l'API delle attività in tempo reale →

Domande frequenti

È l'API WidgetKit ufficiale di Apple?

No. WidgetKit è il framework on-device di Apple, e usarlo direttamente significa costruire e pubblicare la propria app iOS con un'estensione widget. PushWard è un'API dei widget di iOS indipendente: l'app PushWard include l'estensione WidgetKit, e le tue richieste HTTP decidono cosa mostra.

Con quale rapidità si aggiornano i widget?

Ogni PATCH innesca un push leggero che dice a WidgetKit di ricaricare il widget, così gli aggiornamenti arrivano in genere entro pochi secondi. Un limitatore di push per widget (da 1 secondo a 1 ora) raggruppa le sorgenti a raffica, mantenendo gli aggiornamenti entro il budget che iOS concede all'estensione.

I widget funzionano sulla schermata di blocco e in StandBy?

Sì. I widget di PushWard possono essere aggiunti alla schermata Home, alla schermata di blocco e a StandBy dell'iPhone. Gli slot accessori compatti della schermata di blocco mostrano un layout condensato, e toccandone uno si apre l'azione al tocco configurata.

I destinatari devono avere un'app installata?

Sì — l'app iOS gratuita di PushWard (iOS 26 o versioni successive) visualizza i widget e li registra nel selettore dei widget di iOS. Non c'è nulla da costruire o inviare all'App Store.

Prova l'API dei widget di iOS

Costruisci il payload di un widget nel playground e guardalo comparire su un iPhone simulato, oppure leggi la guida introduttiva e registra il tuo primo widget con curl in pochi minuti.