Notifiche Push

Invia notifiche Web Push ai tuoi utenti e lascia che l’AI si occupi di tutto il collegamento.

Nota

La consegna reale delle notifiche push al browser è disponibile quando il tuo ambiente Proyecta Cloud ha l’adattatore di consegna web-push abilitato (PUSH_DELIVERY_ADAPTER=web-push). Con questo attivo, viene emessa una coppia di chiavi VAPID P-256 valida e le notifiche vengono recapitate ai browser in ascolto. Quando è disattivato, il ciclo si completa comunque — le sottoscrizioni vengono salvate e gli invii si risolvono — ma la chiave VAPID è un segnaposto, quindi non viene prodotta alcuna consegna reale e i messaggi vengono registrati nel log anziché inviati. Se le tue notifiche push non arrivano, questo adattatore è la prima cosa da verificare.

Ogni app Proyecta può inviare notifiche push al browser e alle PWA dei suoi utenti. Proyecta gestisce la generazione delle chiavi VAPID, l’archiviazione delle sottoscrizioni, la gestione dei topic e la consegna — senza bisogno di account di terze parti.

Come funziona

Le notifiche push in Proyecta seguono il ciclo di vita standard di Web Push in quattro passaggi:

1. Enable — le chiavi VAPID vengono generate per la tua app la prima volta che servono
2. Subscribe — registra il dispositivo di un visitatore per ricevere le notifiche
3. Identify — collega una sottoscrizione anonima a un utente autenticato
4. Send — recapita una notifica a utenti specifici, topic o a tutti

I primi tre passaggi avvengono per te all’interno dell’hook usePush(); il quarto lo esegui dal tuo pannello di amministrazione.

Sottoscrivere il dispositivo di un utente

La tua app include un hook usePush() che gestisce l’intero flusso lato browser — recupero della chiave VAPID, registrazione del service worker, creazione della sottoscrizione Web Push, archiviazione del secret e collegamento di una sottoscrizione anonima all’utente non appena effettua l’accesso. Non devi fare nulla di tutto questo a mano:

import { usePush } from '@/hooks/usePush.ts';

function NotifyMeButton() {
    const { supported, subscribed, subscribe, unsubscribe, isPending } = usePush();

    // `supported: false` means this browser cannot do push at all — hide the CTA.
    if (!supported) return null;

    return (
        <button onClick={subscribed ? unsubscribe : subscribe} disabled={isPending}>
            {subscribed ? 'Turn off notifications' : 'Notify me'}
        </button>
    );
}

Esiste anche un blocco già pronto, se ti serve solo il prompt di opt-in:

import { PushOptInButton } from '@/components/blocks/PushOptInButton.tsx';

<PushOptInButton description="Get told the moment a new drop lands." />;

Chiedi all’AI: "Add a 'Notify me' button to the header that opts the visitor into push."

I visitatori anonimi sono supportati — l’hook li sottoscrive con un id generato e ricollega automaticamente quella sottoscrizione al loro account quando effettuano l’accesso, così una notifica inviata in seguito li raggiunge in entrambi i casi.

Inviare una notifica

L’invio è un’azione del proprietario, non qualcosa che fanno le pagine pubbliche della tua app — il browser di un visitatore non deve mai poter inviare push a tutto il tuo pubblico. Nella pratica quotidiana invii dalla sezione Push del pannello di amministrazione della tua app: scrivi il titolo e il testo, scegli un topic o un broadcast generale, e invia prima un test al tuo dispositivo.

Puoi raggiungere tutti, oppure solo i visitatori iscritti a un determinato topic. Una notifica contiene un titolo, un testo e, facoltativamente, un’icona e un’immagine.

Dopo l’invio ottieni il numero di dispositivi raggiunti e di invii falliti. Un’avvertenza: quei numeri riflettono le consegne reali al browser solo quando l’adattatore di consegna web-push è attivo. Con l’adattatore disattivato, il conteggio riflette quante sottoscrizioni archiviate sono state targettizzate, non le consegne effettive — quindi in quel caso non leggerlo come una conferma di consegna.

Topic

I visitatori possono sottoscriversi a topic con nome (ad es. product-updates, weekly-digest) invece che a un’unica lista tutto-o-niente. Questo è il modo consigliato per gestire gli opt-in — non hai bisogno di tenere traccia tu stesso dei visitor ID per gli aggiornamenti in stile broadcast. I topic compaiono come selettore del pubblico nella sezione Push del pannello di amministrazione.

Annullare la sottoscrizione

Chiama unsubscribe dallo stesso hook usePush() — contiene già il secret della sottoscrizione, quindi non devi archiviare né passare nulla:

const { subscribed, unsubscribe } = usePush();

{
    subscribed && <button onClick={unsubscribe}>Turn off notifications</button>;
}

Lascia che l’AI faccia il collegamento

Non devi scrivere nulla di tutto questo a mano. Chiedi all’AI:

• "Add a 'Notify me' button to the header that opts the visitor into push notifications."
• "Put a push opt-in prompt on the product page, but only show it to visitors who haven't already subscribed."
• "Add a topic called 'breaking-news' that visitors can opt into from the footer."

Avvertenze

• Il preview non invia push reali. Le notifiche push funzionano solo sulla versione pubblicata della tua app, perché i browser richiedono HTTPS su un’origin reale.
• iOS richiede una PWA. Su iOS 16.4+, Web Push funziona solo da una Progressive Web App installata (aggiunta alla schermata Home), non direttamente da Safari.
• Il permesso si chiede una volta sola. Se un utente nega il permesso per le notifiche, i browser non ti consentono di richiederglielo di nuovo in modo programmatico. Devi guidarlo alle impostazioni del browser o del dispositivo.

Prossimamente

• Invii pianificati e basati su eventi — invia automaticamente in base a eventi dell’app o a una pianificazione
• Deep linking — apri una schermata specifica dell’app quando l’utente tocca la notifica