Phonegap Android Background Service Plugin - Getting started

Summary

This blog describes how to integrate the Android Background Service Plugin into an existing Phonegap project.

The Android Background Service Plugin will simply write out to Logcat every minute.  This simply exercise demonstration that Phonegap can start a service and that the service will continue interdependently of if the Phonegap app is closed.



Getting Started

This blog assumes that you are working with the Phonegap project created in Eclipse similar to the Hello World application described here.  It should also be noted that I am using Cordova 1.8.1 in this blog.  Where differences exist for Cordova 2.x.x I have appended relevant notes.

Download the following files from here:

Installing into your project


Installing the Core Plugin

The Core Plugin are files and configuration that will be needed for any implementation that uses the Plugin.

1) Cordova 1.8.1 > Copy the backgroundserviceplugin.jar to /libs
    or
    Cordova 2.x.x > Copy the backgroundserviceplugin-2.0.0.jar to /libs.

2) Refresh the project (right click project and refresh) to ensure that the jar is visible in the library.


3) Ensure that the jar is listed in the Build Path for the project.  Right click on the /libs folder and go to Build Paths/ Configure Build Paths.  Then in the Libraries tab, add the jar library to the project.



4) Cordova 1.8.1 > Copy the backgroundService.js into assets/www.
    or
    Cordova 2.x.x > Copy the backgroundService-2.0.0 into assets/www.

5) Refresh the project to ensure that the js file is visible in the folder.



6) Cordova 1.8,1 > Add the following line to res/xml/plugins.xml
    or
    Cordova 2.x.x > Add the following line to res/xml/config.xml


7) Ensure that following are in the AndroidManifest.xml.  This line sets permission so that the Background Service can be restarted on device boot.

8) Add the BootReceiver detail to the AndroidManifest.xml.  This should be added within the Application node.

9) Your manifest file should look similar to the below:


This completes the steps to install the core Plugin.  The next steps are for specific Background Service.

Install the Background Service 

The files and setup for a Background Service will be unique to the service.  In this instance we are putting in MyService which will output a hello message to the LogCat.

1) Create a Package called "com.yournamespace.yourappname" (if you don't already have)

2) Copy the MyService.java file into src\com\yournamespace\yourappname folder (and refresh the project):



3) Cordova 1.81 > Copy the myService.js and index.html files into assets\www folder:
     or
     Cordova 2.x.x > Copy the myService-2.0.0.js and index-2.0.0.js into assets\www folder:


4) Add the following lines to the AndroidManifest.xml.  This should be added within the Application node:

5) Your manifest file should look similar to the below:


6) Cordova 2.0.0 only > Update the MainActivity to load index-2.0.0.html rather than index.html.

The application is now good to go.

Running the application

Running the application should give you the following screen initially:

From here you can:

When the service is running (and the timer is enabled), you should get messages similar to the below in the LogCat:



Next Steps

In coming blogs I shall explain the Background Service Plugin in more detail as well a take you through the steps of extending the Plugin yourself.

I really hope this helps.  I look forward to comments.

Spread the love

If you find the Background Service Plugin useful then spread the love.

All the work I do on the Plugin is done in my spare time - time I would otherwise be spending taking my wife out for a nice meal or helping my lad find vinyl records (he's currently very much into The Smiths, Fleetwood Mac and Kate Bush).

The Plugin is free and will always remain free. I will continue to develop, maintain and distribute the Plugin under the MIT License.

Labels: , , , ,