Notificações Push

Envie notificações Web Push para seus usuários e deixe a IA cuidar de todo o resto.

Nota

A entrega real de push pelo navegador está disponível quando o ambiente do Proyecta Cloud tem o adaptador de entrega web-push habilitado (PUSH_DELIVERY_ADAPTER=web-push). Com ele ativo, um par de chaves VAPID P-256 válido é emitido e as notificações são entregues aos navegadores inscritos. Quando está desativado, tudo ainda funciona de ponta a ponta — as inscrições são armazenadas e os envios resolvem — mas a chave VAPID é um placeholder, então nenhuma entrega real é produzida e as mensagens são registradas em log em vez de enviadas. Se seus pushes não estão chegando, esse adaptador é a primeira coisa a verificar.

Todo app do Proyecta pode enviar notificações push para navegadores e PWAs para seus usuários. O Proyecta gerencia a 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 — as chaves VAPID são geradas para seu app na primeira vez em que são necessárias
2. Subscribe — registra o dispositivo de um visitante para receber notificações
3. Identify — vincula uma inscrição anônima a um usuário autenticado
4. Send — entrega uma notificação para usuários específicos, tópicos ou para todos

As três primeiras acontecem automaticamente dentro do hook usePush(); a quarta você faz pelo seu painel de administração.

Inscrever o dispositivo de um usuário

Seu app já vem com um hook usePush() que cuida de todo o fluxo no navegador — buscar a chave VAPID, registrar o service worker, criar a inscrição Web Push, armazenar o secret e vincular uma inscrição anônima ao usuário assim que ele fizer login. Você não faz nada disso à mão:

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>
    );
}

Também há um bloco pronto, caso você queira apenas o prompt de opt-in:

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

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

Peça à IA: "Add a 'Notify me' button to the header that opts the visitor into push."

Visitantes anônimos são suportados — o hook os inscreve com um id gerado e revincula essa inscrição à conta deles automaticamente quando fazem login, de modo que uma notificação enviada depois chega a eles de qualquer forma.

Enviar uma notificação

O envio é uma ação do dono, não algo que as páginas públicas do seu app fazem — o navegador de um visitante jamais pode disparar push para todo o seu público. No dia a dia, você envia pela seção Push do painel de administração do seu app: escreva o título e o corpo, escolha um tópico ou faça broadcast para todos, e envie um teste para o seu próprio dispositivo primeiro.

Você pode direcionar para todos ou apenas para os visitantes inscritos em um tópico específico. Uma notificação carrega um título, um corpo e, opcionalmente, um ícone e uma imagem.

Após o envio, você recebe a contagem de quantos dispositivos foram alcançados e quantos falharam. Uma ressalva: esses números só refletem entregas reais no navegador quando o adaptador de entrega web-push está ativo. Com ele desativado, a contagem reflete quantas inscrições armazenadas foram direcionadas, e não as entregas reais — então não a interprete como confirmação de entrega nesse caso.

Tópicos

Os visitantes podem se inscrever em tópicos nomeados (por exemplo, product-updates, weekly-digest) em vez de uma única lista tudo-ou-nada. Esta é a forma recomendada de gerenciar opt-ins — você não precisa rastrear visitor IDs por conta própria para atualizações em estilo broadcast. Os tópicos aparecem como o seletor de público na seção Push do painel de administração.

Cancelar inscrição

Chame unsubscribe a partir do mesmo hook usePush() — ele já guarda o secret da inscrição, então não há nada para você armazenar ou repassar:

const { subscribed, unsubscribe } = usePush();

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

Deixe a IA configurar tudo

Você não precisa escrever nada disso à mão. Peça à IA:

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

Considerações importantes

• 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), e não diretamente pelo Safari.
• A permissão é uma decisão ú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ê precisará orientá-lo às configurações do navegador ou do dispositivo.

Em breve

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