The simple way to add a prepopulated SQLite DB in PhoneGap

A common scenario for PhoneGap applications is that you want to include a prepopulated database that contains required information for the app. The plugin often used is the SQLitePlugin for iOS and Android.

There are several ways to accomplish this:

1. Use the storage API directly and populate the database with SQL statements (ref).
2. Write the code to manually to copy the prepopulated DB (ref1, ref2).

Option 1 quickly becomes considerable work for a DB containing a lot of data. The performance of this solution when requiring many queries can also be quite poor. Option 2 might be considerably better, because it gives you the option to populate the SQLite DB and bundle it with your PhoneGap application. This method uses the SQLitePlugin for both Android and iOS. However, you will need to write a bit of code manually to create the copy functionality, where the bundled DB-file is copied to the correct location for both implementations.

Because of these issues I decided to update the SQLitePlugins for Android and iOS to support prepopulated SQLite DB files. This blog article will show how to setup and use the plugins in your own PhoneGap projects.

I will not show how to create and setup PhoneGap projects, there are Getting Started guides available for both Android and iOS.

The first step after the PhoneGap projects are created is to setup the prepopulated DB files. This can easily be achieved using several SQLite tools, for example SQLite Manager for Firefox. Next we move on to how the DB files should be included in your projects.

Android

Plugin source code: https://github.com/jarlehansen/PhoneGap-SQLitePlugin-Android

For Android the DB file should be placed in the assets-folder, remember to use the file name *.db.
For example: TestDB.db

The DB files are loaded the same way as a standard database, with the command:

 var db = window.sqlitePlugin.openDatabase({  
   name : "TestDB"  
 });  

You do not need to include the .db file-extension, this is done automatically by the plugin.

What happens next is that the SQLitePlugin will first see if the DB already exists, if it does not it will try to find the prepopulated DB-file in the assets folder and copy this to the correct location. If no prepopulated DB file is found, this step is simply skipped. For all executions after this initial setup, the plugin will use the copied database.

iOS

Plugin source code: https://github.com/jarlehansen/PhoneGap-SQLitePlugin-iOS

The iOS setup is very similar. Copy the db-file into the project, for example directly under the project root.

The files are loaded exactly the same way as in the Android example shown. The plugin also works similar to Android, in that it only copies the prepopulated DB the first time and only if it is found in the application bundle.

And that is it, no need to manually write the insert statements or write custom code. Hopefully this will make it easier to add a prepopulated SQLite DB to your project. Let me know what you think in the comments :)


References (used when I created the plugin code):
- http://gauravstomar.blogspot.ca/2011/08/prepopulate-sqlite-in-phonegap.html
- http://www.reigndesign.com/blog/using-your-own-sqlite-database-in-android-applications

Quick start guide for Google Cloud Messaging

This is a guide for setting up a working Android push-messaging project. It uses the following dependencies:

• android-gcm-quickstart archetype (https://github.com/akquinet/android-archetypes), currently version 1.0.10-SNAPSHOT
• GCMUtils (http://gcmutils.googlecode.com/)

Start by running the android-gcm-quickstart archetype:

 mvn archetype:generate -DarchetypeGroupId=de.akquinet.android.archetypes \   
 -DarchetypeArtifactId=android-gcm-quickstart -DarchetypeVersion=1.0.10-SNAPSHOT \   
 -DgroupId=my.project.package -DartifactId=my-project-name -DsenderId=[my-sender-id]  

Add you own project settings for groupId, artifactId and senderId. See the GCM getting started guide for information on how to get the senderId and apiKey: http://developer.android.com/google/gcm/gs.html

Configure the API Key, you can do this in three ways:

 

1. Add a property in the .m2/settings.xml file:

2. In the maven command, add a system property:

 gcmutils:run-server -DapiKey=  

3. Add the tag in the pom.xml (not recommended):




Start the test-server by running the following maven command:

 mvn gcmutils:run-server  

Open your browser on: http://localhost:9595
Start the main Android activity in the project and try to send a push message from the webpage to the connected device. By default the message should be shown by Logcat.

Now you hopefully have a working GCM project in Android!
For more detailed information, see the GCMUtils webpage

GCMUtils - utility classes for Google Cloud Messaging

During Google IO 2012 Google updated their push messaging service (from C2DM), releasing Google Cloud Messaging. GCM includes features such as:

• Ease of use, no sign-up forms
• Battery efficiency
• Statistics available through the Developer Console
• Rich set of new APIs

While C2DM was a really cool technology, it was somewhat complicated to get implemented correctly. GCM have improved this by providing a much simpler API. Let me show a few examples.

These two lines of code provides verification for the device (that it supports push messaging) and the Manifest-file:

 GCMRegistrar.checkDevice(context);  
 GCMRegistrar.checkManifest(context);  

To get the registration id, code similar to this example can be used:

 String regId = GCMRegistrar.getRegistrationId(context);  
 if ("".equals(regId)) {   
   GCMRegistrar.register(context, SENDER_ID);   
 } else {   
   Log.i("Already registered, regId:" + regId);   
 }   

For more information, go to the official GCM page.

As shown above, the GCMRegistrar-class contains several useful methods. However, there are aspects that the standard GCM-library does not support.

GCMUtils (https://code.google.com/p/gcmutils)

This is why my new open source project, GCMUtils, was created. This library is a collection of helpful utility classes and methods, built on top of the standard GCM API. It is created to be used in combination with GCM.

It provides features such as:

• Registration id handling 

 GCMUtils.getAndSendRegistrationId(this);  

• Extended verification 

 GCMUtils.checkExtended(this);  

• Simple configuration 

 # Required  
 receiver-url=  
 sender-id=  
 # optional  
 # values: enabled/disabled  
 check-extended=enabled  

• Alternative base intent service with more functionality 

 public class GCMIntentService extends GCMUtilsBaseIntentService {  
  @Override  
  protected void onMessage(Context context, String msg) {  
   Log.i(TAG, "Message received: " + msg);  
  }  
  @Override  
  protected void onError(Context context, String error) {  
   Log.e(TAG, "onError: " + error);  
  }  
 }  

Adding it to your project is easy (copy 2 jar files) and it is created to make to development of GCM apps simpler and more efficient. In my own project this has been a big help, and hopefully this will be useful for others as well.

For more information, go to the features page and the quick start guide.

It is still early in the development of this project, so all feedback is appreciated. There are more features planned to get implemented before a final release is ready.