native.showPopup() — Address Book

Type function
Library native.*
Revision 2017.3060
Keywords native, showPopup, address, contacts

Overview

Displays the operating system's default popup window to access a user's address book and contacts.

Syntax

native.showPopup( name, params )
name (required)

String. The string name of the popup to be shown. For the Address Book plugin, use "addressbook".

params (required)

Table. A table that specifies the properties for the popup. This table requires the option parameter with a value of either "pickContact", "viewContact", "newContact", or "unknownContact". Depending on this value, additional options apply — see the next section for details.

native.showPopup( "addressbook",
    {
        option = "pickContact",  --"pickContact", "viewContact", "newContact", or `"unknownContact"
        --additional options (see below)
    }
)

Options Reference

Valid properties in the params table depend upon the value specified for option.

getPermission

Gets the permission state of your access to the users contacts. If a permission request has not been issued before, then a permission popup will be shown to request permission to the users contacts. One of the following strings are returned upon calling this function, describing the contact access permission state.

  • "authorized": User authorized access to their contacts.
  • "denied": User denied access to their contacts.
  • "restricted": Access to the users contact is restricted due to parental settings.
  • "requestPermission": A permission popup is shown to request access to the users contacts. If a permission request was previously denied, this popup cannot be shown again due to iOS limitations. The only way the user can grant access to your app from this point is to enable your app under Settings > Privacy > Contacts > Select your app. Note: After the function returns, you can call native.showPopup("addressbook", {option = "getPermission"}) to check if the user authorized or denied your request

pickContact

The following additional properties apply if params.option is set to "pickContact":

hideDetails

Boolean. If set to true, the address book will be dismissed upon selecting a contact.

performDefaultAction

Boolean. If set to true, tapping/touching a contact's phone number or email will perform the default system action, for example call the contact or show the compose email UI.

filter

Table. Table of string values indicating the items to show within the detail view section for a contact. For example, filter = { "phone", "email", "birthday" }. The following values are supported:

  • "phone"
  • "email"
  • "address"
  • "birthday"
  • "relatedNames"
  • "socialProfiles"
  • "instantMessagingProfiles"
listener

Function. Listener function to be called when the popup is dismissed. This function is passed an event table which contains the following properties:

  • event.name (string) — Value of "contact".
  • event.type (string) — Value of either "pickContact", "viewContact", "newContact", or "unknownContact", depending on the popup shown.
  • event.data (table) — Table containing data for the selected contact. See Contact Data below for a list of available data.

viewContact

The following additional properties apply if params.option is set to "viewContact":

performDefaultAction

Boolean. If set to true, tapping/touching a contact's phone number or email will perform the default system action, for example call the contact or show the compose email UI.

isEditable

Boolean. If set to true, the user can edit the person's information.

name

String. The name of the contact you wish to view.

filter

Table. Table of string values indicating the items to show within the detail view section for a contact. For example, filter = { "phone", "email", "birthday" }. The following values are supported:

  • "phone"
  • "email"
  • "address"
  • "birthday"
  • "relatedNames"
  • "socialProfiles"
  • "instantMessagingProfiles"
listener

Function. Listener function to be called when the popup is dismissed. This function is passed an event table which contains the following properties:

  • event.name (string) — Value of "contact".
  • event.type (string) — Value of either "pickContact", "viewContact", "newContact", or "unknownContact", depending on the popup shown.
  • event.data (table) — Table containing data for the selected contact. See Contact Data below for a list of available data.

newContact

The following additional properties apply if params.option is set to "newContact":

data

Table. Table containing key/value pairs to pre-fill a new contact's details with. Supported keys include:

  • firstName, middleName, lastName
  • organization, jobTitle, birthday
  • phoneticFirstName, phoneticMiddleName, phoneticLastName
  • prefix, suffix, nickname
  • phoneIphone, phoneMobile, phoneMain, phoneHome, phoneWork
  • faxHome, faxWork, faxOther, pager
  • homeEmail, workEmail
  • homePageUrl, workUrl, homeUrl
  • father, mother, parent, brother, sister, child
  • friend, spouse, partner, assistant, manager
  • homeStreet, homeCity, homeState, homeZip, homeCountry
  • workStreet, workCity, workState, workZip, workCountry
  • socialFacebook, socialTwitter, socialFlickr, socialLinkedIn, socialMyspace, socialSinaWeibo, socialGameCenter
  • instantMessagingAim, instantMessagingFacebook, instantMessagingGaduGadu, instantMessagingGoogleTalk, instantMessagingICQ, instantMessagingJabber, instantMessagingMSN, instantMessagingQQ, instantMessagingSkype, instantMessagingYahoo
listener

Function. Listener function to be called when the popup is dismissed. This function is passed an event table which contains the following properties:

  • event.name (string) — Value of "contact".
  • event.type (string) — Value of either "pickContact", "viewContact", "newContact", or "unknownContact", depending on the popup shown.
  • event.data (table) — Table containing data for the selected contact. See Contact Data below for a list of available data.

unknownContact

The following additional properties apply if params.option is set to "unknownContact":

performDefaultAction

Boolean. If set to true, tapping/touching a contact's phone number or email will perform the default system action, for example call the contact or show the compose email UI.

allowsActions

Boolean. This specifies whether buttons appear to let the user perform actions such as sharing the contact, initiating a call, or sending a text message.

allowsAdding

Boolean. If set to true, the Add to Existing Contact or Create New Contact buttons will be available on the contacts overview screen.

alternateName

String. Alternate name to display instead of the contact's first and last name.

message

String. This string is displayed below alternateName.

data

Table. Table containing key/value pairs to pre-fill an unknown contact's details with. Supported keys include:

  • firstName, middleName, lastName
  • organization, jobTitle, birthday
  • phoneticFirstName, phoneticMiddleName, phoneticLastName
  • prefix, suffix, nickname
  • phoneIphone, phoneMobile, phoneMain, phoneHome, phoneWork
  • faxHome, faxWork, faxOther, pager
  • homeEmail, workEmail
  • homePageUrl, workUrl, homeUrl
  • father, mother, parent, brother, sister, child
  • friend, spouse, partner, assistant, manager
  • homeStreet, homeCity, homeState, homeZip, homeCountry
  • workStreet, workCity, workState, workZip, workCountry
  • socialFacebook, socialTwitter, socialFlickr, socialLinkedIn, socialMyspace, socialSinaWeibo, socialGameCenter
  • instantMessagingAim, instantMessagingFacebook, instantMessagingGaduGadu, instantMessagingGoogleTalk, instantMessagingICQ, instantMessagingJabber, instantMessagingMSN, instantMessagingQQ, instantMessagingSkype, instantMessagingYahoo
listener

Function. Listener function to be called when the popup is dismissed. This function is passed an event table which contains the following properties:

  • event.name (string) — Value of "contact".
  • event.type (string) — Value of either "pickContact", "viewContact", "newContact", or "unknownContact", depending on the popup shown.
  • event.data (table) — Table containing data for the selected contact. See Contact Data below for a list of available data.

Contact Data

The following data is available in the event table of the listener function when the popup is dismissed:

Example

local function onPopupDismiss( event )
    print( "event.name:", event.name )
    print( "event.type:", event.type )

    -- event.data is either a table or nil depending on the option chosen
    print ( "event.data:", event.data )

    -- if there is 'event.data', print its key/value pairs
    if ( event.data ) then
        print( "event.data: {" )

        for k,v in pairs( event.data ) do
            print( k, ":", v )
        end

        print( "}" )
    end
end

local pickContactOptions =
{
    option = "pickContact",
    hideDetails = true,
    performDefaultAction = true,
    filter = { "phone", "email", "birthday" },
    listener = onPopupDismiss
}
native.showPopup( "addressbook", pickContactOptions )