9. Notificações locais (AppsKitSDKLocalNotificationManager)

O AKS inclui um pequeno conjunto de ferramentas para notificações locais — uma fila, um construtor de notificações e um BroadcastReceiver abstrato — que você pode usar para exibir suas próprias notificações locais. O AKS não registra o receiver no manifesto nem faz agendamentos por você; ambas as tarefas são de sua responsabilidade.

9.1 Manifesto

Crie uma subclasse de AppsKitSDKLocalNotificationBroadCastReceiver (conforme mostrado na §9.2) e declare-a como um <receiver>, dentro do mesmo elemento <application> da §2:

<application
    android:name=".YourApplication">

    <receiver
        android:name=".YourNotificationReceiver"
        android:exported="false" />

</application>

Se o app tiver como alvo o Android 13+ (API 33), adicione também a permissão de notificações em tempo de execução — o manifesto do próprio AKS não a declara, portanto ela não será incluída automaticamente na mesclagem de manifestos:

<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />

POST_NOTIFICATIONS é uma permissão em tempo de execução, então você ainda precisa solicitá-la ao usuário (por exemplo, via ActivityResultContracts.RequestPermission()) para que as notificações sejam efetivamente exibidas.

9.2 Adicionando uma notificação à fila

Crie uma subclasse de AppsKitSDKLocalNotificationBroadCastReceiver e implemente checkNotifications() — esse é o ponto em que você decide se está na hora de exibir uma notificação, chamado sempre que o receiver é acionado:

class YourNotificationReceiver : AppsKitSDKLocalNotificationBroadCastReceiver() {

    override fun checkNotifications() {
        addNotificationInQueue(
            NotificationModel(
                id = "daily_reminder",                      // dedup key — a second add with the same id is ignored
                title = "Come back!",
                description = "You have unfinished items waiting.",
                icon = R.drawable.ic_notification,
                notificationId = 1001,                       // the actual Android notification ID passed to notify()
                targetScreen = "com.yourapp.MainActivity"    // fully-qualified Activity class opened on tap
            )
        )
    }
}

Assim que checkNotifications() retorna, onReceive chama automaticamente AppsKitSDKLocalNotificationManager.showNotification(context) — esse método remove da fila o NotificationModel mais antigo e o exibe. Nesse fluxo, você não precisa chamar showNotification diretamente; basta adicionar a notificação à fila dentro de checkNotifications().

Esse fluxo de exibição pela fila verifica a permissão POST_NOTIFICATIONS por conta própria no Android 13+ e, caso ela não tenha sido concedida, ignora a exibição silenciosamente (registrando uma linha no log). Portanto, certifique-se de solicitá-la primeiro, conforme a §9.1.

9.3 Agendamento

O AKS não registra nem aciona esse receiver de forma agendada — você decide quando onReceive é acionado, geralmente usando AlarmManager:

val intent = Intent(context, YourNotificationReceiver::class.java)
val pendingIntent = PendingIntent.getBroadcast(
    context, 0, intent, PendingIntent.FLAG_IMMUTABLE or PendingIntent.FLAG_UPDATE_CURRENT
)

val alarmManager = context.getSystemService(Context.ALARM_SERVICE) as AlarmManager
alarmManager.setRepeating(
    AlarmManager.RTC_WAKEUP,
    System.currentTimeMillis() + intervalMs,
    intervalMs,
    pendingIntent
)

Para intervalMs, você pode definir um intervalo fixo no código ou usar o valor da configuração remota no portal do AKS (HOURS_TO_MAKE_NOTIFICATION, com padrão de 2 horas se não estiver definido). Esse valor é disponibilizado por getTimeIntervalInMilliSeconds() na classe base do receiver, mas o método é protected. Por isso, chame-o de dentro da sua subclasse, e não no trecho de código acima:

class YourNotificationReceiver : AppsKitSDKLocalNotificationBroadCastReceiver() {
    fun intervalMillis(): Long = getTimeIntervalInMilliSeconds()
    override fun checkNotifications() { /* ... */ }
}

AlarmManager.setRepeating não garante horários exatos sob o modo Doze ou as otimizações de bateria — se você precisa de acionamentos confiáveis enquanto o dispositivo está ocioso, reagende com setExactAndAllowWhileIdle a cada acionamento ou use PeriodicWorkRequest do WorkManager (intervalo mínimo de 15 minutos). O AKS não exige nenhuma dessas opções; escolha a que melhor atende ao seu app. Observe também que os alarmes não são mantidos após a reinicialização do dispositivo, a menos que você os registre novamente (por exemplo, em um receiver de BOOT_COMPLETED).

9.4 Exibindo uma notificação diretamente (sem fila)

Para exibir uma notificação imediatamente, sem passar pelo fluxo de fila e receiver descrito acima:

// Tapping opens the Activity at classPath
AppsKitSDKLocalNotificationManager.showNotification(
    context = this,
    id = 2001,
    classPath = "com.yourapp.MainActivity",
    channelId = "general",
    title = "New message",
    message = "You've got a new message waiting.",
    notificationIcon = R.drawable.ic_notification
)

// Or pass a fully-built Intent instead of a class path
AppsKitSDKLocalNotificationManager.showNotification(
    context = this,
    id = 2002,
    intent = Intent(this, MainActivity::class.java).putExtra("from", "notification"),
    channelId = "general",
    title = "New message",
    message = "Tap to view details.",
    notificationIcon = R.drawable.ic_notification
)

Ambas as sobrecargas criam o canal de notificação para você, caso ele ainda não exista. Diferentemente do fluxo com fila da §9.2, nenhuma delas verifica POST_NOTIFICATIONS por conta própria — solicite a permissão em tempo de execução no Android 13+, ou a chamada poderá falhar silenciosamente sem exibir a notificação.