Using BOOT_COMPLETED in Titanium

It is a common requirement to need to restart your app if the user restarts the device. Although this requirement is common, it can get tricky quickly. For example do you want to restart in the foreground or background? What if you want to send a notification instead?

The Android.Tools project has been updated to handle a majority of these scenarios using the new BootReceiver. This component allows you to do the following:

On BOOT_COMPLETED restart your app in either the foreground or background
On BOOT_COMPLETED create a notification with information defined in your project’s tiapp.xml
You can also use Titanium Properties to configure the above options from within your Titanium app.

How does it work?

The BootReceiver is configured to work similar to how a native app would when it receives the BOOT_COMPLETED broadcast. Since Titanium might not yet be loaded, the module will help bootstrap your app based on the configuration elements in your tiapp.xml.

Warning: This functionality requires you update your tiapp.xml file with a few specific elements. I’ve included samples for each scenario, but please plan on spending alittle time exploring in order to get the configurations for your app working properly.

Finding the tiapp.xml entries

The below steps cover how to create the tiapp.xml entries needed for this module to work.

Before installing the module, you will want to build your project for the simulator. It doesn’t matter if the app is empty or event runs. The goal is to simply have Titanium generate a AndroidManifest.xml file. You can find this file in your Project/build/android folder as illustrated below in red.

To avoid the 2373 restart bug, you will need to 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>

Using the information from step #1’s AndroidManifest.xml add an android configuration node to your tiapp.xml.

(a) Add the two permission lines highlighted in Blue.

(b) Add the application node from your AndroidManifest.xml collected in step #1. If you are copying and pasting the example, make sure you change the names to match your project information.

Scenario 1: Restart

The first scenario supported by the module is to restart your Titanium app upon receipt of the BOOT_COMPLETED broadcast.

The following diagram demonstrates how to create a receiver entry in your tiapp.xml to use the BootReceiver module. The section shown in red illstrates the receiver and intent-filter entries needed to be made in order for your app to subscribe to the BOOT_COMPLETED broadcast.

bootType : This meta-data element is required and tells the module which action to take. By using the restart option, the module will restart your application upon receipt of the BOOT_COMPLETED broadcast.
sendToBack : This meta-data element is required if using the bootType of restart. If true, your app will be restarted in the background upon receipt of the BOOT_COMPLETED broadcast. If false, your app will be restarted in the foreground and the user will be presented with the first window of your app.

Please see the sample tiapp.xml and app.js for the full example files.

Scenario 2: Notification

The second scenario supported by the module is publish a notification upon receipt of the BOOT_COMPLETED broadcast.

The following diagram demonstrates how to create a receiver entry in your tiapp.xml to use the BootReceiver module. The section shown in red illustrates the receiver and intent-filter entries needed to be made in order for your app to subscribe to the BOOT_COMPLETED broadcast.

Meta-Data Elements

bootType : This meta-data element is required and tells the module which action to take. By using the notify option, the module will publish a notification using the title and message properties defined in the tiapp.xml receipt of the BOOT_COMPLETED broadcast.
title : This meta-data element is required if using the bootType of notify. The title is used to create the title for the notification that will be published after receipt of the BOOT_COMPLETED broadcast.
message : This meta-data element is required if using the bootType of notify. The message is used to create the message body for the notification that will be published after receipt of the BOOT_COMPLETED broadcast.

Please see the sample tiapp.xml and app.js for the full example files.

Scenario 3: Using Properties

Allowing for the app at runtime to how to handle the BOOT_COMPLETED broadcast allows for handling more complex use cases but requires additional setup. Titanium Properties are mapped to configuration elements in your tiapp.xml. The value from these specific Titanium properties are then to determine the correct action to be taken upon receiving the BOOT_COMPLETED broadcast.

Meta-Data Elements

bootType : This meta-data element is required and tells the module which action to take. By using the propertyBased option, the module will look at the following properties to determine which action to take.
enabled_property_to_reference : This android:value element contains a reference to the Titanium Property the module will reference to see if this feature has been enabled. This property must contain a Boolean value and is false by default.
bootType_property_to_reference : This android:value element contains a reference to the Titanium Property the module will reference to see what action to perform. Just like the primary bootType element, you can use restart or notify to perform the desired actions. Please note all configuration elements such as title, message, sendToBack will be read from the Titanium Properties mapped in your tiapp.xml file.
sendToBack_property_to_reference : This android:value element contains a reference to the Titanium Property the module will reference to see if the app should be restarted in the foreground or background.. This property must contain a Boolean value and is true by default. Please note: This property is only used if the Titanium Property define in bootType_property_to_reference is set to restart.
icon_property_to_reference : This android:value element contains a reference to the Titanium Property the module will reference to determine which Android Resource Id to use when creating the icon for the notification created on receipt of the BOOT_COMPLETED broadcast. Please note: This property is only used if the Titanium Property define in bootType_property_to_reference is set to notify.
title_property_to_reference : This android:value element contains a reference to the Titanium Property the module will reference to determine which Android Resource Id to use when creating the title for the notification created on receipt of the BOOT_COMPLETED broadcast. Please note: This property is only used if the Titanium Property define in bootType_property_to_reference is set to notify.
message_property_to_reference : This android:value element contains a reference to the Titanium Property the module will reference to determine which Android Resource Id to use when creating the message for the notification created on receipt of the BOOT_COMPLETED broadcast. Please note: This property is only used if the Titanium Property define in bootType_property_to_reference is set to notify.