Programação para Dispositivos Móveis II

Aula 15: Notificações Locais Capacitor API

Roteiro da Aula

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!

1

Instalação e Sincronização Nativa

Terminal

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
2

Verificação e Solicitação de Permissões

Android 13+ UX

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

Disparo Imediato (Instantâneo)

Gatilho 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 }
      }
    ]
  });
};
4

Agendamento Futuro (Schedule Trigger)

Gatilho de Tempo (at)

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()}`);
};
5

Gerenciando Notificações Pendentes

Lifecycle & Cancel

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

Compilação Automática do APK (GitHub Actions)

CI/CD Pipeline

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.