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 responsabilidad tuya.

9.1 Manifiesto

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

<application
    android:name=".YourApplication">

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

</application>

Si tu aplicación apunta a Android 13+ (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 incluirá automáticamente al fusionar los manifiestos:

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

POST_NOTIFICATIONS es un permiso en tiempo de ejecución, así que debes solicitarlo al usuario (por ejemplo, mediante ActivityResultContracts.RequestPermission()) antes de poder mostrar 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 llama 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 de la cola el NotificationModel más antiguo 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+ y, si no se ha concedido, omite la notificación sin mostrar ningún aviso (aunque escribe una línea en el registro). 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 lo activa de forma programada: 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 un intervalo fijo en el código o usar el valor establecido en 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 se obtiene mediante 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 bajo 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 impone 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 tú (por ejemplo, desde un receptor de BOOT_COMPLETED).

9.4 Mostrar una notificación directamente (sin cola)

Para mostrar 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 notificaciones 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+; de lo contrario, es posible que la llamada no muestre la notificación ni indique el fallo.