El arsenal de Android – Planificadores de trabajo

Una práctica biblioteca de Android para configurar una forma de alarma más fácil de lo que es

¿Qué y por qué?

El marco de trabajo de Android tiene una biblioteca considerablemente grande con muchos tipos de alarma diferentes para configurar una alarma… pero quizás demasiado grande. Es perfectamente razonable que el marco de Android tenga un Administrador de alarmas que admita diferentes tipos de alarmas y sea flexible para trabajar con otras partes del marco. Pero esto pone a los desarrolladores en la posición de tener que consumir tanto tiempo y administrar tantas partes diferentes del marco (base de datos, receptores de transmisión, calendario, etc.) para crear, quizás uno de los tipos más simples de aplicaciones móviles: un despertador.

Para muchos casos, las aplicaciones que necesitan configurar una alarma constante (para un simple despertador o para otros usos, como una aplicación que le recuerda beber agua, tomar pastillas, etc.) no requieren nada diferente entre sí, sin embargo, como se mencionó. arriba, toma algo de tiempo y requiere cierto conocimiento sobre las diferentes bibliotecas de Android y el desarrollador tiene que enfrentar varias situaciones (reiniciar el dispositivo, cambiar la configuración de fecha/hora) para asegurarse de que las alarmas sean consistentes.

SmplrAlarm administra todos los módulos necesarios para configurar una alarma adecuada utilizando bibliotecas nativas de Android, proporciona una interfaz API con tecnología de Kotlin DSL y, al final del día, hace que configurar una alarma sea tan simple como:

smplrAlarmSet(applicationContext) {
        hour { hour }
        min { minute }
    }

Cómo instalar

Graduado

allprojects {
 repositories {
  ...
  maven { url 'https://jitpack.io' }
 }
}

dependencies {
        implementation 'com.github.ColdTea-Projects:SmplrAlarm:v1.0.0'
}

Experto en

<repositories>
 <repository>
     <id>jitpack.io</id>
     <url>https://jitpack.io</url>
 </repository>
</repositories>


<dependency>
    <groupId>com.github.ColdTea-Projects</groupId>
    <artifactId>SmplrAlarm</artifactId>
    <version>Tag</version>
</dependency>

Advertencia: La biblioteca requiere una versión mínima de SDK 24

Cambiar registro

[2.0.2] 11.12.2021

1. Integración con Android 12
2. Integración Java 11
3. Kotlin 1.5.31
4. compileSdkVersión 31
5. Actualizaciones de dependencia:
   • org.jetbrains.kotlin: kotlin-stdlib: 1.6.0
   • androidx.core: core-ktx: 1.7.0
   • androidx.appcompat: appcompat: 1.4.0
   • com.google.android.material: material: 1.4.0
   • androidx.test.ext: junit: 1.1.3
   • com.android.tools.build:gradle:7.0.3
   • com.google.gms: servicios de google: 4.3.10
   • koin_versión 3.1.4
6. Notificaciones actualizables
7. Las notificaciones están desactivadas

[v1.3.0] 12.11.2021

Notificación agregadaDismissedIntent: la intención de la acción que se ejecuta cuando se deniega la notificación.

[v1.2.0] 31.10.2021

Adicional

• notificationReceivedIntent: intención de recibir la transmisión que se envía cuando se activa la alarma.

Reparado

• Error de conversión de JSON al convertir extrasKeySet of intent a pantalla completa. Ahora es posible enviar extras en formato String, Int, Long y Double

[v1.1.0] 10.07.2021

Adicional

• infoPairs: nuevo campo en el objeto de alarma que se utiliza para pasar información
• Las intenciones de pantalla completa también devuelven el ID de la solicitud

[v1.0.0] 02.06.2021

• Establecer, actualizar, eliminar alarma
• Escuche y reciba alarmas guardadas
• Una alarma puede constar de: hora, minutos, días de la semana, notificación, canal de notificación, botones de notificación e intención (máx. 29, intención, intención de pantalla completa, estado de actividad.

Cómo utilizar

Configuración de una alarma

Todo lo que SmplrAlarm requiere para configurar una alarma es un número entero que representa la hora y otro número entero que representa el minuto:

smplrAlarmSet(applicationContext) {
        hour { hour }
        min { minute }
    }

Así es, configure una alarma única con una notificación ficticia para ver lo simple que es configurar una alarma con SmplrAlarm. Ahora, hagámoslo más útil.

Alarma repetida

La alarma repetitiva se puede configurar iniciando los días de la semana en los que desea que suene la alarma:

smplrAlarmSet(applicationContext) {
        hour { hour }
        min { minute }
        weekdays {
            monday()
            friday()
            sunday()
        }
    }

Agregar una notificación y un canal de notificación

smplrAlarmSet(applicationContext) {
        hour { hour }
        min { minute }
        weekdays {
            monday()
            friday()
            sunday()
        }
        notification {
            alarmNotification {
                smallIcon { R.drawable.ic_baseline_alarm_on_24 }
                title { "Simple alarm is ringing" }
                message { "Simple alarm is ringing"}
                bigText { "Simple alarm is ringing"}
                autoCancel { true }
            }
        }
        notificationChannel {
            channel {
                importance { NotificationManager.IMPORTANCE_HIGH }
                showBadge { false }
                name { "de.coldtea.smplr.alarm.channel" }
                description { "this notification channel is created by SmplrAlar" }
            }
        }
    
    }

Las notificaciones también se pueden crear con hasta dos botones simplemente enviando el texto del botón y haciendo clic en la intención. Agreguemos los botones de notificación de alarma clásicos de posponer y cerrar siguiendo los pasos a continuación:

Paso 1: crea las intenciones (la clase ActionReceiver en el fragmento debe crearse como una subclase de BroadcastReceiver)

    val snoozeIntent = Intent(applicationContext, ActionReceiver::class.java).apply {
        action = ACTION_SNOOZE
        putExtra(HOUR, hour)
        putExtra(MINUTE, minute)
    }

    val dismissIntent = Intent(applicationContext, ActionReceiver::class.java).apply {
        action = ACTION_DISMISS
    }

Paso 2: implementarlos en el alcance: alarmNotification {}

alarmNotification {
    ...
    firstButtonText { "Snooze" }
    secondButtonText { "Dismiss" }
    firstButtonIntent { snoozeIntent }
    secondButtonIntent { dismissIntent }
}

Los intentos requeridos aquí transmiten un receptor de transmisión. Consulte el siguiente documento para obtener más información sobre los receptores de transmisión:

https://developer.android.com/guide/components/broadcasts

!!! Las notificaciones se actualizan a la versión 2.0.2. ¡Consulte la sección que enumera las actualizaciones en la versión 2.0.2!

Agregar intenciones

SmplrAlarm ofrece poner en marcha intenciones para dos eventos:

1- Al hacer click en la notificación de alarma, se abre la Actividad declarada en intent.

2- Cuando suena la alarma, comienza la actividad indicada en el receiverIntent.

creamos y agregamos intenciones como en el siguiente fragmento:

    val onClickShortcutIntent = Intent(
        applicationContext,
        MainActivity::class.java
    )

    val fullScreenIntent = Intent(
        applicationContext,
        ActivityLockScreenAlarm::class.java
    )

smplrAlarmSet(applicationContext) {
        ...
        intent { onClickShortcutIntent }
        receiverIntent { fullScreenIntent }
    ...
 }

La intención del receptor está diseñada para mostrarse en la pantalla de bloqueo. También se puede usar para otros fines, pero si tiene la intención de usarlo como una pantalla de alarma en su pantalla de bloqueo, consulte la actividad de muestra (ActivityLockScreenAlarm) en la aplicación de demostración.

Identificador de alarma

La biblioteca SmplrAlarm produce y devuelve una identificación única basada en el tiempo cada vez que se llama a smplrAlarmSet (). Esta identificación representa las alarmas almacenadas en la base de datos, así como la identificación de notificación enviada. Observe la clase ActionReceiver de la aplicación de demostración, ya que la misma ID se usó para cancelar la notificación.

Actualizar una alarma

La función de actualización solo admite el cambio de horas, minutos, días de la semana y si la alarma está activada. Para agregar más cambios, la alarma debe borrarse y restablecerse.

smplrAlarmUpdate(applicationContext) {
        requestCode { requestCode }
        hour { 19 }
        min { 23 }
        weekdays {
            friday()
        }
        isActive { isActive }
    }

!!! Las notificaciones también son actualizables desde la versión 2.0.2 en adelante. ¡Consulte la sección que enumera las actualizaciones en la versión 2.0.2!

Cancelar una alarma

    smplrAlarmCancel(applicationContext) {
        requestCode { requestCode }
    }

Escuchando la base de datos

Por último, pero no menos importante, le proporcionamos la información de todas las alarmas configuradas por SmplrAlarm. Dado que las operaciones de la base de datos requieren un proceso asíncrono, es necesario esperar hasta que llegue la respuesta de la consulta. SmplrAlarm se encarga de todo y solo le pide a un oyente que devuelva la información de la alarma en formato JSON.

Para ello primero debemos implementar una instancia de API que nos permita solicitar la lista de alarmas con el listener

var smplrAlarmListRequestAPI: SmplrAlarmListRequestAPI = smplrAlarmChangeOrRequestListener(applicationContext) { jsonString ->
        ...
    whatever you want to do with the alarm list in json format
    ...
    }

Como está configurado, ahora podemos hacer nuestra solicitud:

smplrAlarmListRequestAPI.requestAlarmList()

Y cuando finaliza la consulta, obtiene la lista en el siguiente formato:

{
"alarmItems":[
  {"requestId":745503894, "hour":22, "minute": 29, "weekdays": ["SUNDAY", "THURSDAY"], "isActive": true},
  {"requestId":745503894, "hour":0, "minute": 9, "weekdays": ["SUNDAY", "WEDNESDAY"], "isActive": true}
      ]
}

Si acaba de crear el oyente, puede solicitar actualizaciones; sin embargo, si solo lo hace manualmente, puede solicitar actualizaciones antes de que se realicen. Cada proceso de manipulación de datos en SmplrAlarm (crear, actualizar, eliminar) contiene una llamada al oyente, todo lo que tiene que hacer es enviar a su oyente al interior:

smplrAlarmSet(applicationContext) {
     ...
     requestAPI { smplrAlarmListRequestAPI }
     ...
 }

Recibir notificaciones

Cuando suena la alarma, si está configurada, el sistema genera una notificación que tiene el mismo ID de alarma en la base de datos. SmplrAlarm proporciona esta identificación en la intención que recibe en su receptor de transmisión que ha configurado con las intenciones del botón. Todo lo que necesitas hacer es:

requestId = intent.getIntExtra(SmplrAlarmAPI.SMPLR_ALARM_NOTIFICATION_ID, -1)

(Nuevo) v1.1.0 y posteriores:

Obtenga alertas de intención de pantalla completa

Cuando suena la alarma y se abre una actividad de pantalla completa, SmplrAlarm proporciona el ID de la alarma en la intención que recibe en la actividad de pantalla completa. Todo lo que necesitas hacer es:

requestId = intent.getIntExtra(SmplrAlarmAPI.SMPLR_ALARM_REQUEST_ID, -1)

infoParejas

No importa cuántos campos más agreguemos a smplrAlarm, no podemos cubrirlo todo y simplemente violamos nuestro principio de mantenerlo simple. Sin embargo, esto no cambia el hecho de que en algún momento los usuarios pueden tener que mantener información en la base de datos. Por este motivo hemos añadido infoPairs. infoPairs es un nuevo campo que podemos enviar pares de cadenas en formato de lista:

val extraInformation = listOf("snoozeTime" to "19:15", 
         "note" to "take your pills")
   

smplrAlarmSet(applicationContext) {
     ...
     infoPairs { extraInformation }
 }

Cuando suena la alarma, las intenciones y las notificaciones proporcionan el ID de solicitud. Con este ID de solicitud, puede obtener fácilmente la alarma de la base de datos (consulte la sección Escuchando la base de datos) y usa el infoPair que has guardado.

¡Simple como eso!

(Nuevo) v1.2.0 y posteriores:

Captura alarmas cuando empiezan a sonar

Cuando suena la alarma en LockScreen, SmplrAlarm activa la tarea a la que se ha asignado la intención de pantalla completa y, de lo contrario, solo una notificación. Además de estas dos acciones visuales, SmplrAlarm también envía una transmisión con la intención de BroadcastReceiver que se ha asignado a alarmReceivedIntent

val alarmReceivedIntent = Intent(
    applicationContext,
    AlarmBroadcastReceiver::class.java // this class must be inherited from BroadcastReceiver
)

smplrAlarmSet(applicationContext) {
    ...
    intent { onClickShortcutIntent }
    alarmReceivedIntent { alarmReceivedIntent }
    ...
}

Más tarde, cuando se active la alarma, se llamará al método onReceive de AlarmBroadcastReceiver. En esta clase puede obtener alarmId de la siguiente manera:

override fun onReceive(context: Context?, intent: Intent?) {
        requestId = intent?.getIntExtra(SmplrAlarmAPI.SMPLR_ALARM_REQUEST_ID, -1)?:return
        ...
    }

Con este receptor de transmisión, puede reaccionar cuando la alarma comienza a sonar, ¡así de simple!

(Nuevo) v1.3.0 y posteriores:

Escuchar la desestimación de la notificación

La cancelación de la notificación podrá ser oída mediante la implementación de los siguientes pasos:

Paso 1: crea la intención (la clase ActionReceiver en el fragmento debe crearse como una subclase de BroadcastReceiver)

    val notificationDismissIntent = Intent(applicationContext, ActionReceiver::class.java).apply {
        action = ACTION_NOTIFICATION_DISMISS
    }

Paso 2: implementarlos en el alcance: alarmNotification {}

alarmNotification {
    ...
    notificationDismissedIntent { notificationDismissIntent }
}

Después de implementar estos pasos, su clase ActionReceiver recibirá una acción con la clave ACTION_NOTIFICATION_DISMISS cuando el usuario descarte la notificación, ¡simplemente!

(Nuevo) 2.0.2 y posteriores:

Las notificaciones ahora están deshabilitadas:

Todas las notificaciones enviadas por smplrAlarm no tienen sonido a partir de esta versión. Las notificaciones en esta API fueron diseñadas para usarse con alarmas que presumiblemente tienen su propio sonido. Sin embargo, al establecer la intención de recepción de la alarma, puede capturar la transmisión a la hora de la alarma y usarla para reproducir los sonidos que desee para las notificaciones.

Notificaciones actualizables

¡SmplrAlarm es aún más flexible ahora! La versión 2.0.2 y posteriores ahora admiten la actualización de notificaciones. El uso es exactamente el mismo con smplrAlarmSet(). Todo lo que necesitas hacer es:

smplrAlarmUpdate(requireContext().applicationContext) {
  requestCode { binding.alarmId.text.toString().toInt() }
  .
  .
  notification {
      NotificationItem(
   smallIcon = R.drawable.ic_baseline_change_circle_24,
   title = "I am changed",
   message = "I am changed",
   bigText = "I am changed",
   ...
   ..
   .
      )
  }
  .
  .
     }

¡Simple como eso!