Looking for access to Android’s native AlarmManager in your Titanium project?
Using the new benCoding.AlarmManager you can now schedule alarms and services easily.
Want To Download The Module?
You can download the compile module here. Before getting started please take a look at the “Before You Start” section in the documentation and download the full example project located here.
Interested In The Source?
The source is available in the benCoding.AlarmManager repo on GitHub.
Before You Start
- You need Titanium 1.8.2 or greater
- This module requires Android 2.2 or greater
- Take a look at the full example project located here before starting.
How Does It Work?
The AlarmManager module provides an API for create AlarmManager alerts. The module also provides methods that allow you to schedule your Titanium Android Services to be launched. This is an easy method for scheduling code execution even when your app isn’t active.
addAlarmNotification
The addAlarmNotification allows you to schedule an Alarm that will then create an notification.
You can create an AlarmNotification using the below properties:
- contentTitle– (Required) The title of the notification
- contentText– (Required) The text of the notification
- minute– (Required) The minute of the start time.
- hour– (Optional) The hour you want to start the alarm
- day– (Optional) The day you want to start the alarm
- month– (Optional) The month you want to start the alarm
- year– (Optional) The year you want to start the alarm
- playSound(Optional) Play the default notification sound when alarm triggered.
- vibrate(Optional) Vibrate the device on notification. Please note this requires the vibrate permission.
- showLights(Optional) Activate notification lights on device when alarm triggered.
- icon– (Optional)The icon of the notification
- repeat – (Optional) Used to schedule a repeating alarm. You can provide a millisecond value or use the words hourly, daily, monthly, yearly.
Please note if you omit the day, month, and year parameters the module will assume you mean to make the alarm effective from today and add the number of minutes provided.
The valid repeat options are:
- hourly
- daily
- monthly
- yearly
You can also provide a millisecond value to schedule your own repeat frequency.
addAlarmService
The addAlarmService allows you to schedule an Alarm that will run a service within your Titanium App.
Before using this method you will need to define a service and re-compile your project. After recompiling your project open your /build/AndroidManifest.xml to file your full service name. This is important as Titanium generates this name. To learn more about Android Services please read the documentation here.
You can create an AlarmService using the below properties:
- service– (Required) The full service name from your AndroidManifest.xml to be run.
- minute– (Required) The minute of the start time.
- hour– (Optional) The hour you want to start the alarm
- day– (Optional) The day you want to start the alarm
- month– (Optional) The month you want to start the alarm
- year– (Optional) The year you want to start the alarm
- interval– (Optional) The value used to create an interval service. This value must be in milliseconds.
- forceRestart– (Optional) Force the service to restart if it is already running.
- repeat – (Optional) Used to schedule a repeating alarm. You can provide a millisecond value or use the words hourly, daily, monthly, yearly.
Please note if you omit the day, month, and year parameters the module will assume you mean to make the alarm effective from today and add the number of minutes provided.
The valid repeat options are:
- hourly
- daily
- monthly
- yearly
You can also provide a millisecond value to schedule your own repeat frequency.
cancelAlarmNotification
This method cancels all alarms submitted using the addAlarmNotification method. Unfortunately if you want to cancel only one alarm you need to cancel them all and re-submit. This is due to how Android handles pendingIntents.
cancelAlarmService
This method cancels all alarms submitted using the addAlarmService method. Unfortunately if you want to cancel only one alarm you need to cancel them all and re-submit. This is due to how Android handles pendingIntents.
Receivers
Android Alarm’s work using BroadcastReceivers. In order to have your Titanium project subscribe to the Alarms it generates you need to add the receivers into your tiapp.xml file.
The benCoding.AlarmManager uses two receivers. One for each kind of Alarm you can schedule. See below for the example.
<receiver android:name="bencoding.alarmmanager.AlarmNotificationListener"></receiver> <receiver android:name="bencoding.alarmmanager.AlarmServiceListener"></receiver>
Documentation & Examples
Full documentation is available here, additionally there is a fully functional sample project available for download here. Please note the same project is not included in your module zip file.
Show Me Some Code
Since the AlarmManager module requires the setup of BroadcastReceivers and specific service names I would recommend taking a look at the example app.js before starting.
Please find below a code snippet from the example project showing how to use a few of the methods.
//Import our module into our Titanium App
var alarmModule = require('bencoding.alarmmanager');
var alarmManager = alarmModule.createAlarmManager();
//Set an Alarm to publish a notification in about two minutes
alarmManager.addAlarmNotification({
icon: Ti.Android.R.drawable.star_on, //Optional icon must be a resource id or url
minute:2, //Set the number of minutes until the alarm should go off
contentTitle:'Alarm #1', //Set the title of the Notification that will appear
contentText:'Alarm & Notify Basic', //Set the body of the notification that will apear
playSound:true, //On notification play the default sound ( by default off )
vibrate:true, //On notification vibrate device ( by default off )
showLights: true, //On notification show the device lights ( by default off )
});
//Below is an example on how you can provide a full date to schedule your alarm
//Set an Alarm to publish a notification in about two minutes and repeat each minute
alarmManager.addAlarmNotification({
year: now.getFullYear(),
month: now.getMonth(),
day: now.getDate(),
hour: now.getHours(),
minute: now.getMinutes() + 2, //Set the number of minutes until the alarm should go off
contentTitle:'Alarm #3', //Set the title of the Notification that will appear
contentText:'Alarm & Notify Scheduled', //Set the body of the notification that will apear
repeat:60000 //You can use the words hourly,daily,weekly,monthly,yearly or you can provide milliseconds.
//Or as shown above you can provide the millesecond value
});
//Schedule a service to be run (once) in about two minutes
alarmManager.addAlarmService({
//The full name for the service to be called. Find this in your AndroidManifest.xml Titanium creates
service:'com.appworkbench.alarmtest.TestserviceService',
minute:2 //Set the number of minutes until the alarm should go off
});
//Schedule a service to be run (once) in about two minutes, then to run at the same time each day
alarmManager.addAlarmService({
//The full name for the service to be called. Find this in your AndroidManifest.xml Titanium creates
service:'com.appworkbench.alarmtest.TestserviceService',
year: now.getFullYear(),
month: now.getMonth(),
day: now.getDate(),
hour: now.getHours(),
minute: now.getMinutes() + 2, //Set the number of minutes until the alarm should go off
repeat:'daily' //You can use the words hourly,daily,weekly,monthly,yearly or you can provide milliseconds.
});
bencoding 