Saving Contacts with PhoneGap Android

Frequently on the Phonegap Google Group I'm responding to users who have problems saving contacts on Android using PhoneGap. There are a number of steps that you need to follow in order to be able to save a contact on your device/emulator and I thought I'd go over them here so that others can benefit.

First off is the choice of API you use when creating your emulator. Most people will use the "Android" version of the API level they want to target. Amazingly enough this is a bad choice. Say you wanted to target API level 10 you shouldn't select "Android 2.3.3 - API Level 10" instead you should select "Google APIs (Google Inc.) - API Level 10".

Update 2012/02/29: I've fixed an issue in PhoneGap 1.4.1 and you should now be able to save contacts to the local database and not require a Google account anymore.

So let's get started by creating a new AVD:

Once you have a your new Google API AVD setup you'll want to create you PhoneGap application and use the following HTML as your main page:

Once you've got the code in place run the application in the AVD created earlier. You should see the following:

At this point you are probably thinking "well that's not good". Well no it isn't but at least there is a good reason for it. Your AVD has no account so let's go create one. You have to go to Applications -> Settings

Accounts & Sync

Click Add an Account

I recommend using the Google account option as it is the easiest to setup and it's far more likely you have access to a Google account for testing rather than an MS Exchange account.

Select Next

Select Create if you don't have a Google account or Sign In if you already do.

Provide your user id and password, then click Sign In.

You should see the following success screen.

Now click Finish Setup and re-run your application and you should see this screen:

Alright, we did it. Let's head into the Contacts application to make sure that the contact has saved successfully. To which we are greeted with this screen:

Now at this point I've probably lost all credibility with you but wait don't click off the post just yet as this is completely normal. Click the Menu button and select Display Options

Then you'll need to select the new account that you added and click the checkbox to show All Contacts.

Then once you click the Done button you'll be taken back to the Contacts application and you will finally get to see the contact you saved.

That is a bit of a pain to setup but once it is done you won't need to ever do it again as long as you keep your AVD around.

However, there are two other things that trip up people when they are trying to save on contact from a PhoneGap application. The first is that people forget to put the WRITE_CONTACTS permission in their manifest file. You should have this line in your AndroidManifest.xml file:

<uses-permission android:name="android.permission.WRITE_CONTACTS"></uses-permission>

The second gotcha is that the developer never actually calls the save() method. You see the code:

var contact = navigator.contacts.create();

Does not persist the contact to the internal database. Rather it creates an object contact that is an instance of a Contact. If you want to save your contact to the database you need to call contact.save():

contact.save(successCB, errorCB);

So if you've followed all of these instructions and you still can't seem to get the contact to save come on over to the PhoneGap Google Groups and ask for some help. You might just have found a bug. Please mention details of what the problem is. A bug report called "Contacts are broke" doesn't give anyone enough information to help you.