Notifiche Push

Invia notifiche Web Push ai tuoi utenti. Configura con l’SDK e lascia che l’AI colleghi tutto automaticamente.

Nota

Le API per le notifiche push sono parzialmente funzionali a livello di SDK — le sottoscrizioni vengono salvate e le chiamate di invio si risolvono senza errori. Tuttavia, la consegna effettiva delle push al browser non è ancora abilitata in produzione: le chiavi VAPID restituite da enable() sono byte casuali, non chiavi EC P-256 valide, quindi la sottoscrizione dal browser (pushManager.subscribe) fallirà finché la consegna in produzione non sarà abilitata. I messaggi vengono registrati ma non inviati ai dispositivi. La consegna in produzione è in arrivo.

Ogni app Proyecta può inviare notifiche push al browser e alle PWA ai propri utenti. L’SDK di Proyecta gestisce la generazione delle chiavi VAPID, l’archiviazione delle sottoscrizioni, la gestione degli argomenti e la consegna — nessun account di terze parti richiesto.

Come funziona

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

1. Enable — genera le chiavi VAPID per la tua app (una tantum)
2. Subscribe — registra il dispositivo di un utente per ricevere le notifiche
3. Identify — collega una sottoscrizione anonima a un utente autenticato
4. Send — consegna una notifica a utenti specifici, argomenti o a tutti

Tutte e quattro sono disponibili sotto proyecta.pushNotifications nell’SDK.

Abilita le push per la tua app

La prima chiamata genera una chiave pubblica VAPID di cui il browser ha bisogno per creare una sottoscrizione. È idempotente — chiamarla di nuovo restituisce la stessa chiave.

import Proyecta from '@proyecta-ai/sdk';

const proyecta = new Proyecta({ apiKey: process.env.PROYECTA_API_KEY });

const { vapidPublicKey } = await proyecta.pushNotifications.enable();

Chiedi all’AI: "Enable push notifications and store the VAPID key in a PROYECTA_VAPID_PUBLIC_KEY env var".

Sottoscrivi il dispositivo di un utente

Sul client, crea una sottoscrizione Web Push con la chiave VAPID, poi inviarla al server insieme a un visitorId:

// client side
const registration = await navigator.serviceWorker.ready;
const subscription = await registration.pushManager.subscribe({
    userVisibleOnly: true,
    applicationServerKey: PROYECTA_VAPID_PUBLIC_KEY,
});

// server side (or via your API route)
const { secret } = await proyecta.pushNotifications.subscribe({
    visitorId: currentUser?.id ?? generateAnonymousId(),
    subscription: {
        endpoint: subscription.endpoint,
        keys: {
            auth: subscription.keys.auth,
            p256dh: subscription.keys.p256dh,
        },
    },
});
// Store `secret` on the client — it's required to unsubscribe or identify later

Usa un ID utente autenticato come visitorId se l’utente è autenticato, oppure un UUID generato per i visitatori anonimi.

Collega le sottoscrizioni anonime agli utenti

Quando un visitatore anonimo effettua il login, collega la sua sottoscrizione esistente all’ID utente autenticato, così la prossima chiamata a send potrà raggiungerlo:

await proyecta.pushNotifications.identify({
    secret: storedSubscriptionSecret,
    userId: authenticatedUser.id,
});

Invia una notifica

Puoi targetizzare ID visitatori specifici, argomenti, entrambi (come unione) o trasmettere a tutti. Ometti sia visitorIds che topics per fare un broadcast.

// Send to specific users
await proyecta.pushNotifications.send({
    title: 'Your order has shipped',
    body: 'Track it from your dashboard',
    visitorIds: ['user_123', 'user_456'],
    data: { orderId: 'ord_789' }, // custom payload
});

// Send to everyone subscribed to a topic
await proyecta.pushNotifications.send({
    title: 'New feature just dropped',
    topics: ['product-updates'],
    icon: 'https://cdn.example.com/icon.png',
    image: 'https://cdn.example.com/banner.png',
});

// Broadcast to all subscribers
await proyecta.pushNotifications.send({
    title: 'Scheduled maintenance at 2am UTC',
});

send restituisce { sent, failed } così puoi sapere com’è andata la consegna. Il conteggio sent nella risposta stub attuale riflette il numero di sottoscrizioni archiviate targetizzate, non le consegne effettive al browser — non fare affidamento su di esso come conferma di consegna finché la consegna in produzione non sarà abilitata.

Argomenti

Gli utenti possono sottoscrivere argomenti con nome (es. product-updates, weekly-digest) tramite la sub-risorsa proyecta.pushNotifications.topics. Questo è il metodo consigliato per gestire le liste di opt-in — non è necessario tenere traccia dei visitor ID per aggiornamenti in stile broadcast.

Annulla la sottoscrizione

Rimuovi una sottoscrizione usando il secret restituito da subscribe:

await proyecta.pushNotifications.unsubscribe({ secret });

Lascia che l’AI colleghi tutto

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

• "Enable push notifications for my app. Register a service worker, call pushNotifications.subscribe on the client after the user grants permission, and store the secret in localStorage."
• "Send a push to all users subscribed to the 'breaking-news' topic whenever a new article is published."
• "After a user signs in, call pushNotifications.identify to link their anonymous subscription to their user ID."

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’origine 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 è una tantum. Se un utente nega il permesso per le notifiche, i browser non consentono di richiedere nuovamente il permesso in modo programmatico. Devi guidarli alle impostazioni del browser o del dispositivo.

Prossimamente

• Invii programmati e basati su eventi — invia automaticamente in base a eventi dell’app o a una pianificazione
• Deep linking — apri una schermata specifica nell’app quando viene toccata la notifica