ab-plugin-featNow that Corona Plugins is a reality, we’re seeing a rapid deployment of new features to Corona. Last week, we blogged about the new social plugin. This week, we introduce the Address Book plugin. Right now, this is for iOS devices only, but Android development will soon be underway.

Getting Started

Like all plugins, you need to include the address book in your build.settings file:

settings =
{
   plugins =
   {
      --key is the name passed to Lua's 'require()'
      ["CoronaProvider.native.popup.addressbook"] =
      {
      --required
      publisherId = "com.coronalabs",
      },
   },
}

Basic Code

The address book plugin is implemented via the native.showPopup() API, just like the social plugin. You do not need to “require” anything to use this. In your code, simply call:

native.showPopup( "addressbook", params )

The params table is the most important here — this table is mandatory and consists of options that dictate how the popup will behave. At this time, the plugin can fetch an existing contact, update an existing contact, create a new contact, or find a contact. Let’s inspect the format of this table:

local params = {
   option = "pickContact",
   listener = onContactsComplete
}
  • option (string) — dictates the behavior of the contact dialog. Options are:
     “pickContact” – pick a contact from a listing of all contacts contained in the users address book.
    “newContact” – create a new contract entry.
    “viewContact” – open an individual contact entry.
    “unknownContact” – add to a new or append to an existing contact.
  • listener — a callback function to handle the data returned from the address book. Only required for “pickContact”.

Extending the Options

Depending on the specified option from above, there are additional entries that can be specified in the options table. Let’s go through these per option:

“pickContact”

  • hideDetails (true/false) — if true, the address book display will be dismissed upon selecting a contact. If set to false, the address book will display the detail view of the contact selected.

“newContact”

  • data (table) — a table of fields to “pre-fill” the new contact form with. For example:
data = {
   workEmail = "support@coronalabs.com",
   homePageUrl = "https://coronalabs.com"
}

The list of basic data elements includes — but is not limited to — the following:

  • firstName
  • lastName
  • organization
  • homePhone
  • workPhone
  • homeEmail
  • workEmail

NOTE:  this is not an exhaustive and complete list. People may have multiple addresses (email or physical), custom phone numbers, etc.

“viewContact”

The viewContact option requires that you to pass a name query to search for. It will show the contact details for the nearest matching contact.

  • name (string) — the name of the contact to search for.
  • performDefaultAction (true/false) — if true, tapping on phone numbers will make a call; tapping on an email address will start an email to that user.
  • isEditable (true/false) — if true, you can open the record to edit it. If false, then it’s view only.
  • filter (table) — a table of strings representing which fields you want to display on the resulting view of the contact. The ordering of these is not important.

“unknownContact”

This will let you add to an existing contact.

  • performDefaultAction (true/false) — if true then tapping/touching a contacts phone number or email will perform the default iOS action (such as call the contact or show the email composition popup).
  • allowsActions (true/false) — specifies whether buttons appear to let the user perform actions such as sharing the contact, initiating a FaceTime call, or sending a text message.
  • allowsAdding (true/false) — the person’s record is only added to the address book database if allowsAdding is true and the user taps the “Add to Existing Contact” or “Create New Contact” button.
  • alternateName (string) — provides a value that is displayed instead of the first and last name.
  • message — text displayed below alternateName.
  • data — a table of fields to add/append to a contact. For example:
    data = {
       workEmail = "support@coronalabs.com",
       homePageUrl = "https://coronalabs.com"
    }

Callback Listener

Only “pickContact” requires a callback listener. The callback listener essentially brings back data from a “pickContact” address popup. The specified function is passed an event table that contains an event.name, event.type and an event.data table. This event.data table contains the returned values from the contact. Depending on what information is filled out for that individual contact, this table will contain that information. See the entry above that lists the potential fields that can be returned.

A very basic contact picker could be written like this:

local function onContactsComplete( event )
   --if there is event.data, print its key/value pairs
   if ( event.data ) then
      print( event.data.firstName .. " " .. event.data.lastName )
      print( event.data.phoneIphone or event.data.phoneMobile or event.data.phoneHome )
   end
end

local pickContactOptions = {
   option = "pickContact",
   hideDetails = true,
   performDefaultAction = true,
   listener = onContactsComplete,
}

native.showPopup( "addressbook", pickContactOptions )

In Summary

Accessing the user’s contacts in iOS is that easy! To get up and running as quickly as possible, you may want to check out the sample code in our GitHub repository. Additionally, please check out the documentation for the plugin.

  1. I get an error when downloading the plugin for using it on the simulator. It tells me that the plugin is not available for the version of the Simulator (2013.1137). How can I solve this problem?

  2. I’m kind of new to using plugins so sorry if the answer to this is simple…
    I want to keep one codebase, so I include the plugin in the build.settings and build for both platforms right?
    But I end up having to comment out the lines in build.setting for android builds because I get this error:

    A device build error occurred on the server.
    BuildID: 52847a366b72e
    Error: Get plugin failed.
    Publisher: com.coronalabs
    Plugin: CoronaProvider.native.popup.addressbook

    Is there a way around this with plugins that only support one platform?

    • This should work:

      settings =
      {
      plugins =
      {
      –key is the name passed to Lua’s ‘require()’
      [“CoronaProvider.native.popup.addressbook”] =
      {
      –required
      publisherId = “com.coronalabs”,
      supportedPlatforms = { iphone = true },
      },
      },
      }

      • Great, thanks for that.
        Is there support for native.canShowPopup() on this plugin? I can’t seem to get it to filter off android at the moment. I want to disable certain UI and functionality for unsupported platforms and don’t really want to use system.getInfo(“platformName”) because this will mean copious amounts of changes when you develop cross platform support for the plugin.

  3. I have noticed that some contact fields (Facebook, Twitter, etc.) are in table format. What data type is used to store these fields in Sqlite?

    • SQLite doesn’t really have a table data type. You would be best to pull out the individual fields and store them in the type appropriate field, of set up a relation table since it’s a many-to-one relationship (that is each person can have multiple contacts. You would have one table with individual fields for each thing in the facebook, twitter , etc contact table along with an ID of the record on the person it belonged to, the type of the contact (facebook, twitter, etc). Then when you query the person and have their ID you would do another query from the contacts table getting all records belonging to that ID.

      Rob

  4. How bout getting the list of all the user’s contacts returned as one table so we can then iterate through it? I need to be able to choose mutliple users from the user’s contact list, and the above sample only allows me to click on one person. 😐 Appreciate the help!

    -Mario

  5. Rik Veldhuizen says:

    Hi Rob,

    Any update on making this available for Android?

    I had to revert to using facebook friends mechanism to see who else has the application installed, but I’d like to make sure that my application can also be used by non-facebook users.

    • Rob Miracle says:

      Its still on our list of things we want to do, but there are higher priority items in front of it right now.

      Rob

  6. Hi Rob,

    It is more than a year now, when will Android Address Book integration come ?
    Can’t you get this priortized higher ? Whole lot of business applications will be possible if single plugin to pick Android and iOS Address book will be available.

    Is there any other pointer or reference, which I can follow, to get Android Contact book list within Corona?

    Thanks..

  7. I just went to look at the feedback site to see how many votes this has:

    http://feedback.coronalabs.com/forums/188732-corona-sdk-feature-requests-feedback/suggestions/5639593-address-book

    It has 8 votes. I can’t really go to engineering and ask them to prioritize this when there are items with dozens and hundreds of votes that we would need to get to first. It would help to get more votes. You could also ask an Enterprise subscriber to build the plugin and then host it through Gremlin Interactive’s 3rd party plugin library.

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title="" rel=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>