9. Notificaciones locales (AppsKitSDKLocalNotificationManager)

AKS incluye un pequeño conjunto de herramientas para notificaciones locales: una cola, un constructor de notificaciones y un BroadcastReceiver abstracto que puedes usar para mostrar tus propias notificaciones locales. AKS no registra el receptor en su manifiesto ni programa nada por ti; ambas tareas son tu responsabilidad.

9.1 Manifiesto

Crea una subclase de AppsKitSDKLocalNotificationBroadCastReceiver (como se muestra en §9.2) y declárala como un <receiver>, integrado en el mismo elemento <application> de §2:

<application
    android:name=".YourApplication">

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

</application>

Si tu aplicación está orientada a Android 13 o posterior (API 33), añade también el permiso de notificaciones en tiempo de ejecución. El manifiesto de AKS no lo declara, por lo que no se añadirá automáticamente al combinar los manifiestos:

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

POST_NOTIFICATIONS es un permiso en tiempo de ejecución, por lo que también debes solicitarlo al usuario (por ejemplo, mediante ActivityResultContracts.RequestPermission()) antes de poder publicar notificaciones.

9.2 Añadir una notificación a la cola

Crea una subclase de AppsKitSDKLocalNotificationBroadCastReceiver e implementa checkNotifications(): es el punto donde decides si corresponde mostrar una notificación y se invoca cada vez que se activa el receptor:

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

Justo después de que termine checkNotifications(), onReceive llama automáticamente a AppsKitSDKLocalNotificationManager.showNotification(context): extrae el NotificationModel más antiguo de la cola y lo muestra. En este flujo no tienes que llamar a showNotification; basta con añadir la notificación a la cola dentro de checkNotifications().

Este flujo de visualización desde la cola comprueba por sí mismo POST_NOTIFICATIONS en Android 13 o posterior y, si no se ha concedido, omite la notificación sin avisar al usuario (aunque escribe una línea en el registro). Por eso, asegúrate de haber solicitado el permiso antes, tal como se indica en §9.1.

9.3 Programación

AKS no registra este receptor ni programa su activación: tú decides cuándo se ejecuta onReceive, normalmente mediante 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, puedes definir tu propio intervalo fijo en el código o usar el valor de la configuración remota del portal de AKS (HOURS_TO_MAKE_NOTIFICATION, cuyo valor predeterminado es de 2 horas si no se configura). Ese valor está disponible a través de getTimeIntervalInMilliSeconds() en la clase base del receptor, pero el método es protected, así que debes llamarlo desde tu subclase y no desde el código anterior:

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

AlarmManager.setRepeating es inexacto cuando se aplica Doze o las optimizaciones de batería. Si necesitas que la alarma se active de forma fiable mientras el dispositivo está inactivo, vuelve a programarla con setExactAndAllowWhileIdle cada vez que se active, o usa PeriodicWorkRequest de WorkManager (con un intervalo mínimo de 15 minutos). AKS no exige ninguna de las dos opciones; elige la que mejor se adapte a tu aplicación. Ten en cuenta también que las alarmas no se conservan tras reiniciar el dispositivo, a menos que vuelvas a registrarlas (por ejemplo, desde un receptor de BOOT_COMPLETED).

9.4 Mostrar una notificación directamente (sin cola)

Para publicar una notificación de inmediato, sin pasar por el flujo de cola y receptor anterior:

// 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 sobrecargas crean el canal de notificación si aún no existe. A diferencia del flujo con cola de §9.2, ninguna comprueba por sí misma POST_NOTIFICATIONS: debes solicitar el permiso en tiempo de ejecución en Android 13 o posterior; de lo contrario, la llamada podría no publicar la notificación sin mostrar ningún error.