teaching machines

SENG 440: Lecture 14 – Alarms and Notifications

April 4, 2019 by . Filed under lectures, semester1-2019, seng440.

Dear students,

Today we examine some helpful utilities: notifications and alarms. We’ll write an app that prompts the user to accumulate memories by taking a photo each day. Today we’ll focus on the prompting side of things, saving the camera for later.

Before we forget, here’s your TODO for next time:

Also, don’t forget the following requirements to submit your term 1 project:

The official due date is today, but you are free to keep making changes before Monday.

Let’s start creating our app, which we’ll call Backlog.

Broadcast Receivers

We have seen that Android, like all UI-driven systems, spins around event handling. The user triggers events when interacting with widgets. The device triggers events turning on or off and being rotated. Activities trigger events upon closing. In many cases, these events effect some changes to the user interface. But sometimes we aim for subtler effects. Perhaps we find that the battery has dropped to 20%, and we want to disable a background service. Or we find that the network connection has been lost, and we want to pause a download. Instead of responding to these events with a user-facing Activity, we can provide a BroadcastReceiver—which is designed to receive messages but is not tightly coupled to a screenful of interface like an activity.

Compare to Activity, our BroadcastReceiver has no lifecycle or persistent state. Its code is therefore much simpler:

class AlarmReceiver : BroadcastReceiver() {
  override fun onReceive(context: Context, intent: Intent) {
    Log.d("FOO", "Received message ${intent.action}!")
  }
}

The intent may have some extras that interest us, so let’s log those too while we explore:

fun Bundle.toParamsString() = keySet().map { "$it -> ${get(it)}" }.joinToString("\n")

class AlarmReceiver : BroadcastReceiver() {
  override fun onReceive(context: Context, intent: Intent) {
    Log.d("FOO", "Received message ${intent.action} with\n${intent.extras.toParamsString()}")
  }
}

We must also declare our received in the manifest:

<receiver
  android:name=".AlarmReceiver"
  android:enabled="true"
  android:exported="true">
</receiver>

Suppose we want our receiver to get invoked when the battery level ticks up or down. In older versions of Android, we announced the implicit intents that we wanted to receive in an intent-filter element nested in receiver element in the manifest. Apparently too many apps were firing on system events, leading to slowdown. But more recent versions require that we dynamically register and unregister our receivers. We can do this via our Activity callbacks:

class MainActivity : AppCompatActivity() {
  private val AlarmReceiver = AlarmReceiver()

  ...

  override fun onStart() {
    super.onStart()
    registerReceiver(AlarmReceiver, IntentFilter(Intent.ACTION_BATTERY_CHANGED))
  }

  override fun onStop() {
    super.onStop()
    unregisterReceiver(AlarmReceiver)
  }
}

For our app, we want to send a daily notification to the user. Let’s examine how we do that.

Notifications

I’m sure it seemed like a great idea at the time. Instead of the asking the user to constantly check on an information source, we decided to let the information source push a notification when new information had arrived. This system worked great when our checking exceeded the amount of new information. These days we have a constant influx of new information, and notifications are constant. Notifications are focus-breaking interruptions.

In response, modern Android attempts to give users a fair bit of control over which notifications they receive and how. Before an app can send a notification, it must create one or more notification channels. Here we create a channel for our app’s daily reminder notifications and trigger in our main activity:

override fun onCreate(savedInstanceState: Bundle?) {
  ...
  createNotificationChannel()
}

private fun createNotificationChannel() {
  val importance = NotificationManager.IMPORTANCE_DEFAULT
  val channel = NotificationChannel(Notification.CATEGORY_REMINDER, "Daily Reminders", importance).apply {
    description = "Send daily reminders to capture memories"
  }
  val notificationManager: NotificationManager = getSystemService(Context.NOTIFICATION_SERVICE) as NotificationManager
  notificationManager.createNotificationChannel(channel)
}

Here we create a single channel whose internal ID is Notification.CATEGORY_REMINDER. (But we can use any string unique within our app.) If we had different types of notifications to send, we’d create multiple channels with different importance levels. Users set communication preferences for each individual channel in the app’s info screen. Do they hear a beep? Does the phone vibrate? Should a notification override the Do Not Disturb mode?

In our receiver, let’s fire off a notification using NotificationBuilder. We have a few things to configure: an icon, a title, and a message at the minimum. And then we use the NotificationManager to send it off:

override fun onReceive(context: Context, intent: Intent) {
  val notification = Notification.Builder(context, Notification.CATEGORY_REMINDER).run {
    setSmallIcon(R.drawable.camera)
    setContentTitle("A new day, a new memory")
    setContentText("Just a friendly reminder to take today's picture.")
    build()
  }

  val manager = context.getSystemService(Context.NOTIFICATION_SERVICE) as NotificationManager
  manager.notify(0, notification)
}

If we tap on the notification, what happens? Nothing. Ideally, the notification would take us to an activity that prompted us to grab today’s picture. We create an explicit intent for a currently blank PictureActivity but then wrap it up in a PendingIntent to be issued later:

val intent = Intent(context, PictureActivity::class.java).run {
  PendingIntent.getActivity(context, 0, this, 0)
}

Then we include our intent in our notification with setContentIntent:

override fun onReceive(context: Context, intent: Intent) {
  val intent: PendingIntent = Intent(context, PictureActivity::class.java).run {
    PendingIntent.getActivity(context, 0, this, 0)
  }

  val notification = Notification.Builder(context, Notification.CATEGORY_REMINDER).run {
    setSmallIcon(R.drawable.camera)
    setContentTitle("A new day, a new memory")
    setContentText("Just a friendly reminder to take today's picture.")
    setContentIntent(intent)
    build()
  }

  ...
}

One usability issue manifests itself when we run this. When the user clicks on the notification, it doesn’t go away. We can set the notification to automatically cancel with its intent is fired:

val notification = Notification.Builder(context, Notification.CATEGORY_REMINDER).run {
  ...
  setAutocancel(true)
  build()
}

Now that we’ve seen the mechanics of sending a notification, let’s figure out when we want to send one.

Alarms

Notifications fire immediately. To schedule them, we can use Android’s alarm system. Using AlarmManager, we can arrange for a PendingIntent to be issued at some future time. To ping our BroadcastReceiver, we write this explicit intent:

val intent = Intent(applicationContext, AlarmReceiver::class.java).let {
  PendingIntent.getBroadcast(applicationContext, 0, it, 0)
}

AlarmManager gives us several scheduling options. We can schedule the intent at a named absolute time or at some time relative to now. We can schedule it once, or make it a recurring alarm. While we test things, let’s just schedule a one-shot relative alarm that will appear 100 milliseconds in the future:

val alarmManager = getSystemService(Context.ALARM_SERVICE) as AlarmManager
alarmManager.set(AlarmManager.ELAPSED_REALTIME, SystemClock.elapsedRealtime() + 100, intent)

But what we really want is to schedule a repeating notification at the beginning of each day. Since some users are larks and some are night owls, let’s let the user pick a time.

Time Picker

Android provides a fragment-based dialog hierarchy with a handful of utility dialogs—like one for picking a time. We write our own subclass of DialogFragment, which defaults to displaying 6 AM:

class TimePickerFragment : DialogFragment() {
  override fun onCreateDialog(savedInstanceState: Bundle?): Dialog {
    return TimePickerDialog(activity, listener, 6, 0, false)
  }

  var listener: TimePickerDialog.OnTimeSetListener? = null
}

We expose a listener for changes to the time. It can’t be passed as a constructor parameter because fragments can be instantiated outside of your control—such as when they are included in an XML layout. We show this dialog from the main activity:

override fun onCreate(savedInstanceState: Bundle?) {
  ...
  setReminderTime()
}

private fun setReminderTime() {
  val fragment = TimePickerFragment()
  fragment.listener = this
  fragment.show(supportFragmentManager, null)
}

Since we register the activity as the listener, we need it to implement the OnTimeSetListener interface. The onTimeSet method will run our scheduling code, which we switch to repeat daily at an absolute time:

class MainActivity : AppCompatActivity(), TimePickerDialog.OnTimeSetListener {
  ...

  override fun onTimeSet(picker: TimePicker, hour: Int, minute: Int) {
    val today = Calendar.getInstance().apply {
      timeInMillis = System.currentTimeMillis()
      set(Calendar.HOUR_OF_DAY, hour)
      set(Calendar.MINUTE, minute)
    }

    val intent = Intent(applicationContext, AlarmReceiver::class.java).let {
      PendingIntent.getBroadcast(applicationContext, 0, it, 0)
    }

    val alarmManager: AlarmManager = getSystemService(Context.ALARM_SERVICE) as AlarmManager
    alarmManager.setInexactRepeating(AlarmManager.RTC, today.timeInMillis, AlarmManager.INTERVAL_DAY, intent)
  }
}

With a 24-hour span, you might think this would be hard to test. And you’re right, kind of. But if we schedule an alarm in the past, it fires quickly to make up for lost time.

Handling Reboot

There’s one final issue that we probably won’t discover right away. Alarms do not persist across reboots. It is the responsibility of our app to reschedule any alarms when the device powers on. But how can we make this automatic? With a BroadcastReceiver that responds to ACTION_BOOT_COMPLETED events!

Since we need to call the scheduling code from both the Activity and a BroadcastReceiver, let’s factor out the scheduling to a helper utility:

object Utilities {
  fun scheduleReminder(context: Context, hour: Int, minute: Int) {
    val today = Calendar.getInstance().apply {
      timeInMillis = System.currentTimeMillis()
      set(Calendar.HOUR_OF_DAY, hour)
      set(Calendar.MINUTE, minute)
    }

    val intent = Intent(context, AlarmReceiver::class.java).let {
      PendingIntent.getBroadcast(context, 0, it, 0)
    }

    val alarmManager = context.getSystemService(Context.ALARM_SERVICE) as AlarmManager
    alarmManager.setInexactRepeating(AlarmManager.RTC, today.timeInMillis, AlarmManager.INTERVAL_DAY, intent)
  }
}

Next we make a new BroadcastReceiver that schedules the reminder:

class BootReceiver : BroadcastReceiver() {
  override fun onReceive(context: Context, intent: Intent) {
    Utilities.scheduleReminder(context, ?, ?)
  }
}

But what do we do about the hour and minute? Let’s persist them with SharedPreferences! Back in onTimeSet, let’s store the hour and minute for later retrieval:

override fun onTimeSet(picker: TimePicker, hour: Int, minute: Int) {
  val prefs = PreferenceManager.getDefaultSharedPreferences(this)
  prefs.edit().apply {
    putInt("hour", hour)
    putInt("minute", minute)
    apply()
  }

  Utilities.scheduleReminder(applicationContext, hour, minute)
}

Then in onReceive, we can grab the hour and minute from the preferences. We must be careful to reschedule the alarm only if the hour and minute have actively been set. Otherwise we will anger our users. If we’re lucky, they will blame themselves. The shared preferences don’t have a convenient way of checking for a key, but we can use default values as flags:

override fun onReceive(context: Context, intent: Intent) {
  val prefs = PreferenceManager.getDefaultSharedPreferences(context)
  if (prefs.getInt("hour", -1) >= 0) {
    Utilities.scheduleReminder(context, prefs.getInt("hour", 6), prefs.getInt("minute", 0))
  }
}

We must also declare what intents our BootReceiver class receives. We do that in the manifest using the intent-filter element:

<receiver
  android:name=".BootReceiver"
  android:enabled="false"
  android:exported="true">
  <intent-filter>
    <action android:name="android.intent.action.BOOT_COMPLETED" />
  </intent-filter>
</receiver>

The official Android docs recommend starting enabled off at false so you don’t unnecessarily receive these events—before the user has scheduled an alarm. When an alarm does get scheduled, we can flip this property to true by adding these lines to onTimeSet:

override fun onTimeSet(picker: TimePicker, hour: Int, minute: Int) {
  ...
  val receiver = ComponentName(this, BootReceiver::class.java)
  packageManager.setComponentEnabledSetting(receiver, PackageManager.COMPONENT_ENABLED_STATE_ENABLED, PackageManager.DONT_KILL_APP)
}

To receive this intent, we must request the accompanying permission:

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

Now we have an app that sends scheduled notifications. That’s enough for today. Next time we’ll look at taking pictures. See you next time!

Sincerely,

P.S. It’s time for a haiku!

“Time is running out!”
That is why I unsubscribed
My 🕒, their 💰