Notificações Push

Envie notificações Web Push para seus usuários. Configure com o SDK e deixe a IA conectar tudo automaticamente.

Nota

As APIs de notificação push são parcialmente funcionais no nível do SDK — as inscrições são armazenadas e as chamadas de envio são resolvidas sem erro. No entanto, a entrega real de push no navegador ainda não está habilitada em produção: as chaves VAPID retornadas por enable() são bytes aleatórios, não chaves P-256 EC válidas, portanto a inscrição no navegador (pushManager.subscribe) falhará até que a entrega em produção seja habilitada. As mensagens são registradas, mas não enviadas aos dispositivos. A entrega em produção está chegando em breve.

Todo app Proyecta pode enviar notificações push para navegador e PWA aos seus usuários. O SDK do Proyecta cuida da geração de chaves VAPID, armazenamento de inscrições, gerenciamento de tópicos e entrega — sem necessidade de conta em serviços de terceiros.

Como funciona

As notificações push no Proyecta seguem o ciclo de vida padrão do Web Push em quatro etapas:

1. Enable — gerar chaves VAPID para seu app (uma única vez)
2. Subscribe — registrar o dispositivo de um usuário para receber notificações
3. Identify — vincular uma inscrição anônima a um usuário autenticado
4. Send — entregar uma notificação a usuários específicos, tópicos ou a todos

Todos os quatro estão disponíveis em proyecta.pushNotifications no SDK.

Ativar push para seu app

A primeira chamada gera uma chave pública VAPID que o navegador precisa para criar uma inscrição. É idempotente — chamá-la novamente retorna a mesma chave.

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

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

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

Peça à IA: "Enable push notifications and store the VAPID key in a PROYECTA_VAPID_PUBLIC_KEY env var".

Inscrever o dispositivo de um usuário

No cliente, crie uma inscrição Web Push com a chave VAPID e envie-a ao servidor junto com um 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

Use o ID de um usuário autenticado como visitorId se o usuário estiver logado, ou um UUID gerado para visitantes anônimos.

Vincular inscrições anônimas a usuários

Quando um visitante anônimo faz login, vincule a inscrição existente ao ID do usuário autenticado para que o próximo send possa direcioná-lo:

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

Enviar uma notificação

Você pode direcionar visitor IDs específicos, tópicos, ambos (como união) ou fazer um broadcast para todos. Omita visitorIds e topics para transmitir para todos.

// 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 retorna { sent, failed } para que você saiba como foi a entrega. A contagem sent na resposta stub atual reflete o número de inscrições armazenadas direcionadas, não as entregas reais no navegador — não a utilize como confirmação de entrega até que a entrega em produção esteja habilitada.

Tópicos

Os usuários podem se inscrever em tópicos com nomes definidos (por exemplo, product-updates, weekly-digest) por meio do sub-recurso proyecta.pushNotifications.topics. Esta é a forma recomendada de gerenciar listas de opt-in — você não precisa rastrear visitor IDs manualmente para atualizações no estilo broadcast.

Cancelar inscrição

Remova uma inscrição usando o secret retornado pelo subscribe:

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

Deixe a IA conectar tudo

Você não precisa escrever nada disso manualmente. Peça à 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."

Observações importantes

• O preview não dispara pushes reais. As notificações push só funcionam na versão publicada do seu app, pois os navegadores exigem HTTPS em uma origem real.
• iOS requer um PWA. No iOS 16.4+, o Web Push só funciona a partir de um Progressive Web App instalado (adicionado à tela inicial), não diretamente pelo Safari.
• A permissão é uma chance única. Se um usuário negar a permissão de notificação, os navegadores não permitem que você solicite novamente de forma programática. Você precisa orientá-lo a acessar as configurações do navegador ou do dispositivo.

Em breve

• Envios agendados e acionados por eventos — envie automaticamente com base em eventos do app ou em um cronograma
• Deep linking — abra uma tela específica no app quando a notificação for tocada