Notificaciones Push

Envía notificaciones Web Push a tus usuarios. Configura con el SDK y deja que la IA conecte todo automáticamente.

Nota

Las APIs de notificaciones push son parcialmente funcionales a nivel de SDK — las suscripciones se almacenan y las llamadas de envío se resuelven sin error. Sin embargo, la entrega real de push al navegador aún no está habilitada en producción: las claves VAPID que devuelve enable() son bytes aleatorios, no claves P-256 EC válidas, por lo que la suscripción del navegador (pushManager.subscribe) fallará hasta que se habilite la entrega en producción. Los mensajes se registran en log pero no se envían a los dispositivos. La entrega en producción estará disponible próximamente.

Cada app de Proyecta puede enviar notificaciones push para navegador y PWA a sus usuarios. El SDK de Proyecta se encarga de la generación de claves VAPID, el almacenamiento de suscripciones, la gestión de temas y la entrega — sin necesidad de una cuenta de terceros.

Cómo funciona

Las notificaciones push en Proyecta siguen el ciclo de vida estándar de Web Push con cuatro pasos:

1. Enable — genera claves VAPID para tu app (una sola vez)
2. Subscribe — registra el dispositivo de un usuario para recibir notificaciones
3. Identify — vincula una suscripción anónima a un usuario con sesión iniciada
4. Send — entrega una notificación a usuarios específicos, temas o a todos

Los cuatro viven bajo proyecta.pushNotifications en el SDK.

Habilita push para tu app

La primera llamada genera una clave pública VAPID que el navegador necesita para crear una suscripción. Es idempotente — volver a llamarla devuelve la misma clave.

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

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

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

Pídele a la IA: "Enable push notifications and store the VAPID key in a PROYECTA_VAPID_PUBLIC_KEY env var".

Suscribe el dispositivo de un usuario

En el cliente, crea una suscripción Web Push con la clave VAPID y luego envíala al servidor junto con 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 el ID de un usuario autenticado como visitorId si el usuario tiene sesión iniciada, o un UUID generado para visitantes anónimos.

Vincula suscripciones anónimas a usuarios

Cuando un visitante anónimo inicia sesión, vincula su suscripción existente al ID de usuario autenticado para que el siguiente send pueda dirigirse a él:

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

Envía una notificación

Puedes dirigirte a visitor IDs específicos, temas, ambos (como unión), o hacer un broadcast a todos. Omite tanto visitorIds como topics para hacer 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 devuelve { sent, failed } para que sepas cómo resultó la entrega. El conteo sent en la respuesta stub actual refleja el número de suscripciones almacenadas que fueron objetivo, no las entregas reales al navegador — no lo uses como confirmación de entrega hasta que se habilite la entrega en producción.

Temas

Los usuarios pueden suscribirse a temas con nombre (p. ej. product-updates, weekly-digest) a través del sub-recurso proyecta.pushNotifications.topics. Esta es la forma recomendada de gestionar listas de opt-in — no necesitas rastrear visitor IDs tú mismo para actualizaciones estilo broadcast.

Cancela la suscripción

Elimina una suscripción usando el secret que devolvió subscribe:

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

Deja que la IA lo conecte todo

No tienes que escribir nada de esto a mano. Pídele a la IA:

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

Consideraciones importantes

• Preview no envía pushes reales. Las notificaciones push solo funcionan en la versión publicada de tu app porque los navegadores requieren HTTPS en un origen real.
• iOS requiere una PWA. En iOS 16.4+, Web Push solo funciona desde una Progressive Web App instalada (agregada a la pantalla de inicio), no directamente desde Safari.
• El permiso es una sola oportunidad. Si un usuario niega el permiso de notificaciones, los navegadores no te permiten volver a solicitarlo mediante código. Tienes que guiarlo a la configuración de su navegador o dispositivo.

Próximamente

• Envíos programados y activados por eventos — envía automáticamente con base en eventos de la app o un horario
• Deep linking — abre una pantalla específica de la app cuando se toca la notificación