Opening your Android app with BOOT_COMPLETED

Many enterprise apps have the requirement of always running in the background. The most common categories of these apps would be for route management, item tracking, or customer scheduling apps. In your Android Titanium app, you can use an intent filter for the BOOT_COMPLETED action to notify your app that the device has been restarted. The event lifecycle for the BOOT_COMPLETED action is shown in the following diagram:

Opening your Android app with BOOT_COMPLETED

Getting ready

This recipe uses the bencoding.android.tools native module to help with the subscription of the BOOT_COMPLETED broadcast. This module and other code assets can be downloaded from the source provided by the book, or individually through the links provided in the See also section at the end of this recipe. To install this module, simply copy the modules folder shown in the following screenshot into your project.

Also included with the sample recipe is a series of example tiapp.xml and app.js files demonstrating different options in handling the receipt of the BOOT_COMPLETED broadcast. You will need to copy the files highlighted in the following screenshot into your project as they will be used to demonstrate the different available options.

Getting ready

After copying the mentioned files, you will need to click on your tiapp.xml file in Titanium Studio and add a reference to the bencoding.android.tools module as shown in the following screenshot:

Getting ready

How to do it...

This recipe demonstrates how to implement the following scenarios:

  • Auto restarting your app upon receiving the BOOT_COMPLETED broadcast
  • Sending a notification to the user receiving the BOOT_COMPLETED broadcast
  • Using Titanium properties to configure how your app handles the BOOT_COMPLETED broadcast

Required tiapp.xml updates

When a Titanium Android app is launched, the Titanium framework first must be initialized before your app can run. When the app is launched by another service such as the BOOT_COMPLETED broadcast, you will receive a message that the app needs to restart. To avoid this issue, you must add the following properties into your tiapp.xml file:

<property name="ti.android.bug2373.finishfalseroot" type="bool">true</property>
<property name="ti.android.bug2373.disableDetection" type="bool">true</property>
<property name="ti.android.bug2373.restartDelay" type="int">500</property>
<property name="ti.android.bug2373.finishDelay" type="int">0</property>
<property name="ti.android.bug2373.skipAlert" type="bool">true</property>
<property name="ti.android.bug2373.message">Initializing</property>
<property name="ti.android.bug2373.title">Restart Required</property>
<property name="ti.android.bug2373.buttonText">Continue</property>

Scenario A – auto restart

The first BOOT_COMPLETED option provided by the Android.Tools.Receiver module is the ability to restart your app. The typical use case would be to restart your Titanium app when the user restarts his/her device.

Tip

To deploy this scenario to your device using the recipe source, rename the 1.auto_start_tiapp.xml file to tiapp.xml and the 1.app.js to app.js. This will switch the recipe app to use the following scenario details.

Auto restart step 1: adding the receiver to tiapp.xml

The first step in enabling this scenario is to add the receiver entry into the Android configuration node in our project's tiapp.xml file located in the root of your Titanium Project.

<receiver android:exported="true" android:name="bencoding.android.receivers.BootReceiver">
  1. First an intent filter must be added to our receiver, this will subscribe our app to the BOOT_COMPLETED broadcast.
      <intent-filter>
        <action android:name=
        "android.intent.action.BOOT_COMPLETED"/>
      </intent-filter>
  2. Next a metadata node is added with the name bootType. This node is used by the Android.Tools module to determine what boot action should be taken. The following snippet demonstrates how to configure the module to restart the app.
      <meta-data android:name=
      "bootType" android:value="restart"/>
  3. Then a metadata node is added with the name sendToBack. This node is used by the Android.Tools module to determine if the app should be restarted in the background if set to true, or restarted in the foreground if set to false.
      <meta-data android:name=
      "sendToBack" android:value="true"/>
    </receiver>
  4. Finally the RECEIVE_BOOT_COMPLETED permission is added.
    <uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED"/>

Auto restart step 2: testing

The following steps outline how to best test this recipe scenario:

  1. Clean your Titanium solution and push to device.
  2. Make sure the app is not running on your device. You can stop the app using the Force stop option under Settings.
  3. Restart your device.
  4. After the device has been restarted, confirm the date and time displayed on the recipe's main screen.

Scenario B – notification on restart

The second BOOT_COMPLETED option provided by the Android.Tools.Receiver module is the ability to create a notification message when a user restarts his/her device. This can be used to provide a reminder or instructions to the user.

Tip

To deploy this scenario to your device using the recipe source, rename the 2.auto_start_tiapp.xml file to tiapp.xml and the 2.app.js file to app.js. This will switch the recipe app to use the following scenario details.

Notification on restart step 1: adding receiver to tiapp.xml

The first step in enabling this scenario is to add the receiver entry into the Android configuration node in our project's tiapp.xml file.

<receiver android:exported="true" android:name="bencoding.android.receivers.BootReceiver">
  1. First, an intent filter must be added to our receiver, this will subscribe our app to the BOOT_COMPLETED broadcast.
      <intent-filter>
        <action android:name=
        "android.intent.action.BOOT_COMPLETED"/>
      </intent-filter>
  2. Next, a metadata node is added with the name bootType. This node is used by the Android.Tools module to determine what boot action should be taken. The following snippet demonstrates how to configure the module to send a notification message on device restart.
      <meta-data android:name=
      "bootType" android:value="notify"/>
  3. Then a metadata node is added with the name title. This node contains the notification title that will be used.
      <meta-data android:name="title" 
      android:value="Title Sample from tiapp.xml"/>
  4. Then a metadata node is added with the name message. This node contains the notification message that will be used.
      <meta-data android:name="message" 
      android:value="Message Sample from 
      tiapp.xml"/></receiver>
  5. Finally the RECEIVE_BOOT_COMPLETED permission is added.
    <uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED"/>

Notification on restart step 2: testing

The following steps outline the best method to test this recipe scenario:

  1. Clean your Titanium solution and push to device.
  2. Make sure the app is not running on your device. You can stop the app using the Force stop option under Settings.
  3. Restart your device.
  4. Within a few seconds of device reboot, you will see a new message in yournotification tray.

Scenario C – property controlled

The final BOOT_COMPLETED option provided by the Android.Tools.Receiver module is the ability to restart your app. The typical use case would be to restart your Titanium app when the user restarts his/her device.

Tip

To deploy this scenario to your device using the recipe source, rename the 3.auto_start_tiapp.xml file to tiapp.xml and the 3.app.js file to app.js. This will switch the recipe app to use the following scenario details.

Property controlled step 1: adding receiver to tiapp.xml

The first step in enabling this scenario is to add the receiver entry into the Android configuration node in our project's tiapp.xml file.

<receiver android:exported="true" android:name="bencoding.android.receivers.BootReceiver">
  1. An intent filter must be added to our receiver, this will subscribe our app to the BOOT_COMPLETED broadcast.
      <intent-filter>
        <action android:name=
        "android.intent.action.BOOT_COMPLETED"/>
      </intent-filter>
  2. Next, a metadata node is added with the name bootType. This node is used by the Android.Tools module to determine what boot action should be taken. The following code snippet demonstrates how to configure the module to use Titanium properties to determine what action should be taken.
        <meta-data android:name="bootType" 
        android:value=" propertyBased"/>
  3. Metadata nodes are then added to configure the BOOT_COMPLETED receiver. Each node is used to map a Titanium property to a receiver configuration element. For example, the bootType_property_to_reference holds the name of the property to be used to determine the bootType.
    <meta-data android:name="enabled_property_to_reference" android:value="my_enabled"/>
    <meta-data android:name="bootType_property_to_reference" android:value="my_bootType"/>
    <meta-data android:name="sendToBack_property_to_reference" android:value="my_sendtoback"/>
    <meta-data android:name="icon_property_to_reference" android:value="my_notify_icon"/>
    <meta-data android:name="title_property_to_reference" 
    ndroid:value="my_notify_title"/>
    <meta-data android:name="message_property_to_reference" android:value="my_notify_message"/></receiver>
  4. Finally, the RECEIVE_BOOT_COMPLETED permission is added.
    <uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED"/>

Property controlled step 2: create recipe app.js

The Android.Tools module allows for the BOOT_COMPLETED receiver to be configured through Titanium properties. The following code snippet (app.js) demonstrates how to create two different configurations by simply updating the correct Titanium properties.

  1. First, a Ti.UI.Window is created to attach all UI elements.
    var win = Ti.UI.createWindow({
      backgroundColor: '#fff', title: 'BOOT_COMPLETED Example', 
      layout:'vertical',fullscreen:false, exitOnClose:true
    });
  2. Next, a Ti.UI.Button is created to demonstrate how to create a foreground restart.
    var button1 = Ti.UI.createButton({
      title:'Foreground Restart',
      top:25, height:45, left:5, right:5
    });
    win.add(button1);
  3. On the click event of our first button, the properties used to configure our BOOT_COMPLETED receiver are updated.
    button1.addEventListener('click',function(e){
  4. The first action performed in the click event is to set the BOOT_COMPLETED receiver as enabled.
      Ti.App.Properties.setBool('my_enabled',true);
  5. Next, the bootType is set to restart. This will restart our Titanium app on device reboot.
      Ti.App.Properties.setString("my_bootType", "restart");
  6. Then the sendToBack property is set to false. This will restart our Titanium app in the foreground when the user restarts his/her device.
      Ti.App.Properties.setBool("my_sendtoback",false);
    });
  7. Next, a second button is created to demonstrate how to configure the notification.
    var button2 = Ti.UI.createButton({
      title:'Restart Notification',
      top:25, height:45, left:5, right:5
    });
    win.add(button2);
  8. Next a second button is created to demonstrate how to configure notification to be generated when the device is restarted.
    button2.addEventListener('click',function(e){
  9. An action performed in the click event is to set the BOOT_COMPLETED receiver to enabled.
      Ti.App.Properties.setBool('my_enabled',true);
  10. Next the bootType is set to notify. This will send a message after receiving the BOOT_COMPLETED broadcast.
      Ti.App.Properties.setString("my_bootType", "notify");
  11. Next, the notification icon resource identifier is created. This resource identifier will be used to create an icon when the notification is created. If no resource identifier is provided, a star icon will be used by default.
      .App.Properties.setInt("my_notify_icon", 17301618);
  12. Finally the properties linked to the notification title and message are set with new string values. These properties will be used in generating the notification when the device has been restarted.
      Ti.App.Properties.setString(
      "my_notify_title", "Title from property");
      Ti.App.Properties.setString(
      "my_notify_message","Message from property");
    });

Property controlled step 3: testing

The following steps outline how to best test this recipe scenario:

  1. Clean your Titanium solution and push to device.
  2. Open the app, and press the first button (button1). This will update the properties to perform a foreground restart.
  3. Next stop the app; you can stop the app using the Force stop option under Settings.
  4. Restart your device.
  5. After the device is started, the recipe app will be launched in the foreground.
  6. Press the second button (button2). This will update the properties to send a notification on restart.
  7. Restart your device.
  8. Within a few seconds of device reboot, you will see a new message in your notification tray.

See also

The Android.Tools module was used in this recipe to provide the BOOT_COMPLETED functionality. For additional information about this module, please visit the project on Github at https://github.com/benbahrenburg/benCoding.Android.Tools.

For full documentation on the BootReceiver, visit https://github.com/benbahrenburg/benCoding.Android.Tools/tree/master/documentation/bootreceiver.md.

..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset
18.189.189.220