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 agenda nada por você; essas duas tarefas ficam por sua conta.

9.1 Manifesto

Crie uma subclasse de AppsKitSDKLocalNotificationBroadCastReceiver (mostrada na §9.2) e declare-a como um <receiver>, incorporado ao 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, então ela não será incorporada automaticamente ao seu:

<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() — o ponto de extensão para decidir se é 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) — o método remove o NotificationModel mais antigo da fila e o exibe. Nesse fluxo, você não precisa chamar showNotification; basta adicionar a notificação à fila dentro de checkNotifications().

Esse fluxo de exibição pela fila verifica a permissão POST_NOTIFICATIONS no Android 13+ e, se ela não tiver sido concedida, ignora a exibição silenciosamente (registrando uma linha no log). Por isso, certifique-se de solicitá-la antes, conforme a §9.1.

9.3 Agendamento

O AKS não registra nem aciona esse receiver de forma agendada — você decide quando onReceive é chamado, normalmente 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 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; portanto, chame-o de dentro da sua subclasse, e não diretamente no trecho acima:

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

AlarmManager.setRepeating é inexato sob o modo Doze e 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 impõe nenhuma dessas opções; escolha a mais adequada ao seu app. Observe também que os alarmes não persistem após a reinicialização do dispositivo, a menos que você os registre novamente (por exemplo, a partir de 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/receiver 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
)

As duas 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 a permissão POST_NOTIFICATIONS — solicite a permissão em tempo de execução no Android 13+, ou a chamada poderá não exibir a notificação, sem indicar a falha.