Notificări Push

Trimite notificări Web Push utilizatorilor tăi. Configurează cu SDK-ul și lasă AI-ul să conecteze totul automat.

Mențiune

API-urile pentru notificări push sunt parțial funcționale la nivel de SDK — abonamentele se stochează, iar apelurile de trimitere se rezolvă fără erori. Totuși, livrarea efectivă a notificărilor push în browser nu este încă activată în producție: cheile VAPID returnate de enable() sunt octeți aleatori, nu chei EC P-256 valide, deci abonarea în browser (pushManager.subscribe) va eșua până când livrarea în producție va fi activată. Mesajele sunt înregistrate în log, dar nu sunt trimise către dispozitive. Livrarea în producție va fi disponibilă în curând.

Orice aplicație Proyecta poate trimite notificări push în browser și PWA utilizatorilor săi. SDK-ul Proyecta gestionează generarea cheilor VAPID, stocarea abonamentelor, managementul subiectelor și livrarea — nu este necesar niciun cont terț.

Cum funcționează

Notificările push în Proyecta urmează ciclul de viață standard Web Push în patru pași:

1. Activare — generează chei VAPID pentru aplicația ta (o singură dată)
2. Abonare — înregistrează dispozitivul unui utilizator pentru a primi notificări
3. Identificare — leagă un abonament anonim de un utilizator autentificat
4. Trimitere — livrează o notificare unor utilizatori specifici, subiecte sau tuturor

Toate patru sunt disponibile prin proyecta.pushNotifications în SDK.

Activează push pentru aplicația ta

Primul apel generează o cheie publică VAPID de care browserul are nevoie pentru a crea un abonament. Este idempotent — apelarea din nou returnează aceeași cheie.

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

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

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

Cere AI-ului: "Enable push notifications and store the VAPID key in a PROYECTA_VAPID_PUBLIC_KEY env var".

Abonează dispozitivul unui utilizator

Pe client, creează un abonament Web Push cu cheia VAPID, apoi trimite-l la server împreună cu 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

Folosește ID-ul utilizatorului autentificat ca visitorId dacă utilizatorul este conectat, sau un UUID generat pentru vizitatorii anonimi.

Leagă abonamentele anonime de utilizatori

Când un vizitator anonim se conectează, leagă abonamentul său existent de ID-ul utilizatorului autentificat, astfel încât următorul apel send să îl poată ținti:

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

Trimite o notificare

Poți ținti ID-uri specifice de vizitatori, subiecte, ambele (ca reuniune) sau poți trimite tuturor. Omite atât visitorIds, cât și topics pentru a face 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 returnează { sent, failed } pentru a ști cum a decurs livrarea. Numărul sent din răspunsul stub actual reflectă numărul de abonamente stocate țintite, nu livrările efective în browser — nu te baza pe el ca confirmare de livrare până când livrarea în producție va fi activată.

Subiecte

Utilizatorii se pot abona la subiecte cu nume (ex. product-updates, weekly-digest) prin sub-resursa proyecta.pushNotifications.topics. Aceasta este modalitatea recomandată de a gestiona listele de opt-in — nu trebuie să urmărești singur ID-urile vizitatorilor pentru actualizări de tip broadcast.

Dezabonare

Elimină un abonament folosind secretul returnat de subscribe:

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

Lasă AI-ul să conecteze totul

Nu trebuie să scrii nimic din acestea manual. Cere AI-ului:

• "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."

Observații

• Preview-ul nu trimite push-uri reale. Notificările push funcționează doar pe versiunea publicată a aplicației tale, deoarece browserele necesită HTTPS pe o origine reală.
• iOS necesită un PWA. Pe iOS 16.4+, Web Push funcționează doar dintr-o Progressive Web App instalată (adăugată pe ecranul principal), nu direct din Safari.
• Permisiunea se acordă o singură dată. Dacă un utilizator refuză permisiunea pentru notificări, browserele nu îți permit să soliciți din nou în mod programatic. Trebuie să îl îndrumi către setările browserului sau ale dispozitivului.

În curând

• Trimiteri programate și declanșate de evenimente — trimite automat pe baza evenimentelor din aplicație sau a unui program
• Deep linking — deschide un ecran specific din aplicație când se apasă pe notificare