Due to the inherent nature of Titanium Android architecture, it can be challenging to determine when the app has been placed into the background or the lock screen has been activated. These actions are important life cycle events to track for password and application access. For example, you might wish to display a login screen within your app if the user has locked their device since last entering your app.
The following recipe demonstrates how to use the Securely framework to check if the user has a lock screen pattern enabled and fire an event when the screen is locked or unlocked.
This recipe uses the Securely native module. This module and other code assets can be downloaded from the source provided by the book. Installing these in your project is straightforward. Simply copy the modules folder into your project as shown in the following screenshot:
After copying the modules folder, you will need to update the tiapp.xml references as demonstrated in the Getting ready section of the Using secure properties recipe.
Once you have added the module folder into your project, you need to create your application namespace in the app.js file and use require to import the module into your code as the following code snippet demonstrates:
//Create our application namespace
var my = {
secure : require('bencoding.securely')
};This recipe uses a single Ti.UI.Window object to host and demonstrate the different available lock screen methods and events. The following code snippet shows how this object is created.
var win = Ti.UI.createWindow({
backgroundColor: '#fff', title: 'Lock Screen Monitor',
fullscreen:false, exitOnClose:true
});This recipe is dependent on the user enabling a passcode or lock pattern. If this feature is not enabled, the recipe will still function by simply providing when the screen has been disabled from a power consumption standpoint.
The following steps discuss how to verify if the user has enabled the lock screen functionality:
- The first step is to create a new
Securely.Platformproxy as shown in the following code snippet:var platform = my.secure.createPlatform();
- The
Securely.Platformproxy provides many security-related methods. When thelockPatternEnabledmethod is called, a Boolean is provided indicating if the user has enabled this feature on their device.if(!platform.lockPatternEnabled()){ alert('lock screen is not enabled on this device'), }
The Securely.LockScreenHelper proxy object provides the initialization methods needed to start monitoring lock screen activity. The following code snippet demonstrates how to use this proxy to start the monitoring process:
- The first step in the lock screen monitoring process is to create a new
Securely.LockScreenHelperproxy as shown in the following code snippet:var lockHelper = my.secure.createLockScreenHelper();
- Next the
startMonitorForScreenOffmethod is called. This registers a broadcast receiver to listen for theACTION_SCREEN_OFFbroadcast.lockHelper.startMonitorForScreenOff();
- Then the
startMonitorForScreenOnmethod is called. This registers a broadcast receiver to listen for theACTION_SCREEN_ONbroadcast.lockHelper.startMonitorForScreenOn();
Both the startMonitorScreenOff and startMonitorScreenOn methods described earlier will emit global events when their subscribed broadcast is received. The following snippet demonstrates how to create application listeners to subscribe to these events:
Ti.App.addEventListener('BCX:SCREEN_OFF',function(e){
Ti.API.info('Last locked at ' +
String.DateFormat(new Date(e.actionTime)));
});
Ti.App.addEventListener('BCX:SCREEN_ON',function(e){
Ti.API.info('Last unlocked at ' +
String.DateFormat(new Date(e.actionTime)));
});Each event is provided information to assist in managing your app state. Using the prior example snippet, the e argument is provided two properties by Securely.
actionName: This is the full Android intent action name.actionTime: This provides date/time in seconds format on when the last event was called. This can be converted into a JavaScript date usingnew Date(e.actionTime).
This recipe uses the focus event on the example Ti.UI.Window to demonstrate how to check if the device has been locked since the last time the Ti.UI.Window had focus. One use of this pattern would be to check if an internal passcode screen should be presented or to check if a session needs to be re-established.
win.addEventListener('focus',function(e){- The
wasLockedmethod is called to determine if the device has been locked.if(lockHelper.wasLocked()){ - The
isShowingLockScreenmethod can also be used to determine if the device is currently presenting the lock screen to the user.if(!lockHelper.isShowingLockScreen()){ - The
resetMonitorForScreenOffmethod can also be used to reset the value returned bywasLocked. This is helpful in tracking if the device has been locked between app sessions.lockHelper.resetMonitorForScreenOff(); } } });
It is important to stop monitoring and remove the global listeners when the app no longer needs this functionality. The following code snippet demonstrates how this is performed using the close event of the Ti.UI.Window.
win.addEventListener('close',function(e){
lockHelper.stopMonitoring();
Ti.App.removeEventListener('BCX:SCREEN_ON',screenON);
Ti.App.removeEventListener('BCX:SCREEN_OFF',screenOFF);
}); - To learn more about the
android.intent.action.SCREEN_ONandandroid.intent.action.SCREEN_OFFintents used, please visit the official Android documentation available at http://developer.android.com/reference/android/content/Intent.html. - This recipe uses the
Securelymodule. For installation details, please review the Getting ready section of the Using secure properties recipe.