Construindo o Engajamento Invisível com Local Notifications
Aprenda a integrar o plugin nativo @capacitor/local-notifications no React, dominar o fluxo de permissões obrigatórias do Android 13+ e disparar notificações imediatas e agendadas.
Push vs Local Notification
Local: Gerada pelo próprio dispositivo (offline, alarmes, lembretes).
Push: Origem em servidor remoto via Firebase/Supabase (chat, ofertas).
Segurança Android 13+ (API 33)
A permissão POST_NOTIFICATIONS não é automática. Se o usuário não conceder no app, o alerta falha silenciosamente!
Instalação e Sincronização Nativa
Instale o pacote oficial do Capacitor no projeto React e execute a sincronização para copiar as pontes nativas para a pasta do Android.
# 1. Instalar o plugin de Notificações Locais npm install @capacitor/local-notifications # 2. Sincronizar o build com o projeto Android nativo npx cap sync
Verificação e Solicitação de Permissões
Antes de disparar qualquer alerta, consulte o status da permissão e solicite caso esteja no estado prompt ou denied.
import { LocalNotifications } from '@capacitor/local-notifications'; const solicitarPermissao = async () => { try { // Checa o estado atual das permissões let status = await LocalNotifications.checkPermissions(); if (status.display !== 'granted') { // Solicita a permissão na tela do sistema Android/iOS status = await LocalNotifications.requestPermissions(); } if (status.display === 'granted') { console.log('Permissão de notificação concedida com sucesso!'); return true; } else { alert('Aviso: Notificações bloqueadas pelo usuário.'); return false; } } catch (error) { console.error('Erro ao pedir permissão:', error); } };
Disparo Imediato (Instantâneo)
Quando omitimos o objeto schedule ou colocamos a data atual, a notificação é exibida imediatamente na barra de status do smartphone.
const dispararNotificacaoImediata = async () => { await LocalNotifications.schedule({ notifications: [ { title: "Haruy Sushi 🍣", body: "Seu pedido #1042 acabou de sair para entrega!", id: 1, // ID numérico único sound: null, attachments: null, actionTypeId: "", extra: { pedidoId: 1042 } } ] }); };
Agendamento Futuro (Schedule Trigger)
Configure o objeto schedule: { at: new Date(...) } para agendar alertas em um momento preciso do futuro, mesmo que o app esteja fechado pelo usuário.
const agendarLembrete = async (segundos) => { // Calcula o horário futuro: momento atual + N segundos const tempoFuturo = new Date(Date.now() + segundos * 1000); await LocalNotifications.schedule({ notifications: [ { title: "Hora do Remédio! 💊", body: "Está na hora de tomar a Amoxicilina 500mg.", id: 42, schedule: { at: tempoFuturo } // Instructs OS to trigger at timestamp } ] }); console.log(`Notificação agendada para: ${tempoFuturo.toLocaleTimeString()}`); };
Gerenciando Notificações Pendentes
Você pode listar notificações agendadas pendentes no sistema ou cancelá-las caso o usuário desista da ação.
// Listar todas as notificações ainda não disparadas const pendentes = await LocalNotifications.getPending(); // Cancelar uma notificação específica pelo ID await LocalNotifications.cancel({ notifications: [{ id: 42 }] });
Compilação Automática do APK (GitHub Actions)
Crie o arquivo .github/workflows/build-apk.yml no seu repositório para gerar o arquivo app-debug.apk na nuvem a cada git push. Consulte a aba dedicada no topo para ver o script YAML completo.