Android: implementing a notification service the right way

One of the key features of Android is the ability for apps to provide notifications that pop up in the status bar. I'll try to explain in this post how you should implement a Service component that polls a web service regularly to check for updates.

The first thing you need is a preferences activity, where the user can set what notifications they want and how often they want your app to check for them. This is easily achieved using a PreferenceActivity, and is not the subject of this post. If you want to learn more on how to create such an activity, click on the aforementioned link.

Once you have your preferences activity, it's time to write your Service. Here are a few key points that you should always respect. I will go into more detail on each one shortly.

• Respect the global background data setting (I don't think a lot of apps do this).
• Do your work in a separate thread. It can happen that your Service will run on the UI thread as one of your activities.
• Obtain a partial wake lock when starting, and release it when you're done. If you don't do this, the system might (and will) kill your service while your background thread is running.
• Call stopSelf() when you're done, in order to free resources.
• Tell the system to not start your Service again if it's killed for more resources.

To explain all of these, I'll provide a skeleton Service that does everything mentioned above. All you have to do is fill in the work specific to your project:

public class NotificationService extends Service { private WakeLock mWakeLock; /** * Simply return null, since our Service will not be communicating with * any other components. It just does its work silently. */ @Override public IBinder onBind(Intent intent) { return null; } /** * This is where we initialize. We call this when onStart/onStartCommand is * called by the system. We won't do anything with the intent here, and you * probably won't, either. */ private void handleIntent(Intent intent) { // obtain the wake lock PowerManager pm = (PowerManager) getSystemService(POWER_SERVICE); mWakeLock = pm.newWakeLock(PowerManager.PARTIAL_WAKE_LOCK, Const.TAG); mWakeLock.acquire(); // check the global background data setting ConnectivityManager cm = (ConnectivityManager) getSystemService(CONNECTIVITY_SERVICE); if (!cm.getBackgroundDataSetting()) { stopSelf(); return; } // do the actual work, in a separate thread new PollTask().execute(); } private class PollTask extends AsyncTask<Void, Void, Void> { /** * This is where YOU do YOUR work. There's nothing for me to write here * you have to fill this in. Make your HTTP request(s) or whatever it is * you have to do to get your updates in here, because this is run in a * separate thread */ @Override protected Void doInBackground(Void... params) { // do stuff! return null; } /** * In here you should interpret whatever you fetched in doInBackground * and push any notifications you need to the status bar, using the * NotificationManager. I will not cover this here, go check the docs on * NotificationManager. * * What you HAVE to do is call stopSelf() after you've pushed your * notification(s). This will: * 1) Kill the service so it doesn't waste precious resources * 2) Call onDestroy() which will release the wake lock, so the device * can go to sleep again and save precious battery. */ @Override protected void onPostExecute(Void result) { // handle your data stopSelf(); } } /** * This is deprecated, but you have to implement it if you're planning on * supporting devices with an API level lower than 5 (Android 2.0). */ @Override public void onStart(Intent intent, int startId) { handleIntent(intent); } /** * This is called on 2.0+ (API level 5 or higher). Returning * START_NOT_STICKY tells the system to not restart the service if it is * killed because of poor resource (memory/cpu) conditions. */ @Override public int onStartCommand(Intent intent, int flags, int startId) { handleIntent(intent); return START_NOT_STICKY; } /** * In onDestroy() we release our wake lock. This ensures that whenever the * Service stops (killed for resources, stopSelf() called, etc.), the wake * lock will be released. */ public void onDestroy() { super.onDestroy(); mWakeLock.release(); } }

You now have a Service that works as it should, awesome. But how do you start it? You use the AlarmManager, of course (I suggest you read it's documentation if you haven't already). But how and when do you schedule it? How do you handle app updates? How do you handle device reboots? Well, here are some guidelines that I hope will make answering these questions much easier:

• Use repeating alarms so that you don't have to always re-schedule yourself in your Service.
• Use inexact repeating alarms so that the system can group together multiple alarms in order to preserve battery life.
• Always cancel an alarm before resetting it.
• When receiving the BOOT_COMPLETED signal, don't immediately start your Service. This would slow down the device too much (it already has a lot of work to do when it boots). Instead, set an alarm.

What I personally do is set an alarm whenever onResume() is called on my main Activity (the one that is launched when the user clicks on the app icon in their launcher), and in a BroadcastReceiver that handles the BOOT_COMPLETED event. Here's some code to help you understand:

MainActivity.java

public void onResume() { super.onResume(); SharedPreferences prefs = PreferenceManager.getDefaultSharedPreferences(this); int minutes = prefs.getInt("interval"); AlarmManager am = (AlarmManager) getSystemService(ALARM_SERVICE); Intent i = new Intent(this, NotificationService.class); PendingIntent pi = PendingIntent.getService(this, 0, i, 0); am.cancel(pi); // by my own convention, minutes <= 0 means notifications are disabled if (minutes > 0) { am.setInexactRepeating(AlarmManager.ELAPSED_REALTIME_WAKEUP, SystemClock.elapsedRealtime() + minutes*60*1000, minutes*60*1000, pi); } }

AndroidManifest.xml

<receiver android:name=".BootReceiver"> <intent-filter> <action android:name="android.intent.action.BOOT_COMPLETED" /> </intent-filter> </receiver> </application> <uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />

BootReceiver.java

public void onReceive(Context context, Intent intent) { // in our case intent will always be BOOT_COMPLETED, so we can just set // the alarm // Note that a BroadcastReceiver is *NOT* a Context. Thus, we can't use // "this" whenever we need to pass a reference to the current context. // Thankfully, Android will supply a valid Context as the first parameter SharedPreferences prefs = PreferenceManager.getDefaultSharedPreferences(context); int minutes = prefs.getInt("interval"); AlarmManager am = (AlarmManager) context.getSystemService(Context.ALARM_SERVICE); Intent i = new Intent(context, NotificationService.class); PendingIntent pi = PendingIntent.getService(context, 0, i, 0); am.cancel(pi); // by my own convention, minutes <= 0 means notifications are disabled if (minutes > 0) { am.setInexactRepeating(AlarmManager.ELAPSED_REALTIME_WAKEUP, SystemClock.elapsedRealtime() + minutes*60*1000, minutes*60*1000, pi); } }

Finally, you've got yourself a fully functional notifications service that stops and starts whenever it should, that behaves the way the user wants it to behave and that plays nicely with the system. This took some researching, so if I saved a bit of your time, leave a comment :)