Android Notifications and Analytics
Scheduler
The BuzzBox Scheduler for Android allows easy implementation of background Tasks
Features
- Run Tasks up to every minute
- Simple creation of Notifications
- Notification History can be optionally saved and shown to the users
- Advanced Notification settings
- Cron string support. I.e. "0 8-19 * * 1,2,3,4,5" will run every hour, from 8am to 7pm, Monday - Friday
- Reschedule after reboot and after clock changes
- Configurable UI for users to change the Notification Settings
- Auto pause if user is not responsive
- Retry on Error
- Server load protection
- Simple RSS Reader integrated
Permission Requirements
BuzzBox Scheduler requires BuzzBox SDK jar and a few permissions in your manifest.xml
<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" /> <!-- to survive across phone reboot --> <uses-permission android:name="android.permission.WAKE_LOCK" /> <!-- to keep the CPU alive while your Task is executed --> <uses-permission android:name="android.permission.VIBRATE" /> <!-- optional, if you want to allow Notification to use the Vibrate feature --> <!-- if your Task need to access the network, you also need --> <uses-permission android:name="android.permission.INTERNET" /> <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
Code Usage
If you have implemented a Task called WeatherTask, scheduling it is as simple as assigning a cron string to it.
SchedulerManager.getInstance() .saveTask(this, "0 8-19 * * 1,2,3,4,5", WeatherTask.class); SchedulerManager.getInstance() .restart(this, WeatherTask.class);
Cron string examples:
*/15 * * * * every 15 minutes
0 * * * 1,2 Only Mondays and Tuesdays, once an hour
*/2 8-14 * * 1,2 Only Mondays and Tuesdays, every 2 hours, from 8am to 2pm
0/30 * * * 1,2,3,4,5|0 * * * 6,7
Every 30 minutes from Mon to Fri, every hour on Sat and Sun
Your Task needs to be saved only once. You can save as many different Tasks as you want but each of them needs to be implemented in a different class.
Once all your Tasks are saved, you can start the Scheduler calling .restartAll(). This needs to be done only once.
A typical use case is to save a Task when the App is first installed and start the scheduler right away.
The Scheduler must also be restarted when the App is upgraded to a new version. We recommend to use the AnalyticsManager
also included in the BuzzBox SDK to distingush these cases.
Example:
// 1. call BuzzBox Analytics
int openAppStatus = AnalyticsManager.onOpenApp(this);
// 2. add the Task to the Scheduler
if (openAppStatus==AnalyticsManager.OPEN_APP_FIRST_TIME) {
// register the Task when the App in installed
SchedulerManager.getInstance().saveTask(this,
"0 8-20/4 * * 1,2,3,4,5", // a cron string
ReminderTask.class);
SchedulerManager.getInstance().restart(this, ReminderTask.class );
} else if (openAppStatus==AnalyticsManager.OPEN_APP_UPGRADE){
// restart on upgrade
SchedulerManager.getInstance().restartAll(this, 0);
}
See the complete source code: HelloWorldActivity.java
Show the Configuration UI
Allow your users to change the Notification Settings.The Settings Activity is included in the sdk and can be configured in the AndroidManifest.xml
First, declare the activity in you AndroidManifest.xml
<activity
android:name="com.buzzbox.mob.android.scheduler.ui.SchedulerPreferenceActivity" />
Open the Settings Activity calling
SchedulerManager.getInstance() .startConfigurationActivity(YourActivity.this, YourTask.class);The configuration is automatically saved when the activity is closed.
The Scheduler Settings looks like this:
Scheduler and Notification UI, embedded in the SDK and customizable
Most of the elements can be configured from the manifest.xml, so you can show to your users only the setting you want them to be able to change. For example, you can hardcode that the scheduler will run every day of the week and leave to your user the possibility to change at what time it will run.
in AndroidManifest.xml
<meta-data android:name="SchedulerPreferenceActivity.show.daysOfWeek" android:value="false" /> <meta-data android:name="SchedulerPreferenceActivity.show.frequency" android:value="false" /> <meta-data android:name="SchedulerPreferenceActivity.show.enabledFromTo" android:value="false" /> <meta-data android:name="SchedulerPreferenceActivity.show.SelectAtWhatTimes" android:value="true" /> <meta-data android:name="SchedulerPreferenceActivity.show.notificationSettings" android:value="true" />
Limitations: the UI is not able to display and save only 2 kinds of cron strings:
- Frequency: "*/20 8-20 * * *" - every 20 minutes
- At specific times: "0 8 * * *|15 9 * * *" - at 8:00 and at 9:15. In this case the Days of the Week of the 2 expressions must match.
Note that the cron expression to run every 30 minutes is "*/30 0 * * *" it actually means that the Task will fire at minute 0 and
at minute 30 of every hour. It does not mean that it will run every 30 minutes from the moment it was saved.
Not yet supported expressions:
- "0 8 * * 1|15 9 * * 2" - at 8am on Mondays and at 9:15 on Tuesdays
- "*/10 8-12 * * *|*/20 13-23 * * *" - Every 10 minutes in the morning and every 20 minutes in the evening
- Every 10 minutes from 8:15 to 9:30
Note that, even if these expressions are not yet supported by the configuration UI, you can use them in the Scheduler if you don't plan to allow your users to change them.
You can also localize the UI using the language based on the device's locale. You have just to add all the strings to the strings.xml under the valuse-xx folder where xx is the country code (i.g. es, it). Take a look here: strings.xml
Advanced features
Auto pause
If you Schedule a Task, it will run forever untill the App will be uninstalled.
If the App is not used anymore, this can be a problem in terms of useless
battery consumption and can be a problem for your server, if the Task is connecting to a web service.
You can ask the Scheduler to shut down the Tasks if the App has not been opened for a specific period of time.
SchedulerManager.getInstance().saveTask(context, 0 8-20/4 * * *", YourTask.class, false, // do not retry 5*24); // shut down after 5 days if the app is not opened
Retry on Error
If configured to do so, the Scheduler will run again your Task if the TaskResult will return an Error.
Save your Task passing true as retryOnError parameter. See code here.
See TaskResult and RetryPolicy to specify the desired behavior.
Server load protection - Adding Randomness
If you are calling a web service from your Task and you have thousands of App configured to wake up at the same time,
you may end up overloading the server with to many contemporaneous requests.
To prevent this, you can add some randomness to the Scheduler (default is 60 seconds).
SchedulerManager.getInstance().saveGlobalRandomness(ctx, 5*60000); // 5 minutes
Just call this once, when the app is installed for the first time
Notification History
BuzzBox SDK can save all the notification that are sent to the user in the local DB and also provides an activity
to show the notification history in a feed-like style. Users can click on an old notification and reopen some older content.
For more information see notification api
Simple RSS Reader integrated
You don't need to write a Task if you just want to download and show an RSS post entry as a Notification.
You can add Notifications to your App to send reminders and / or news to all your users simply by linking an RSS.
- Save the RssReaderTask:
SchedulerManager.getInstance().saveTask(this, "0 9 * * 1,2,3,4,5", RssReaderTask.class);
- Set the RSS url:
RssReaderTask.setRssUrl(context, "http://yourblog.com/feed.rss");