Type function Library native.* Revision Release 2024.3703 Keywords native, showPopup, address, contacts
Displays the operating system's default popup window to access a user's address book and contacts.
native.showPopup( name, params )
String. The string name of the popup to be shown. For the Address Book plugin, use "addressbook".
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)
}
)
Valid properties in the params table depend upon the value specified for option.
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 requestThe following additional properties apply if params.option is set to "pickContact":
Boolean. If set to true, the address book will be dismissed upon selecting a contact.
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.
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"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.The following additional properties apply if params.option is set to "viewContact":
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.
Boolean. If set to true, the user can edit the person's information.
String. The name of the contact you wish to view.
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"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.The following additional properties apply if params.option is set to "newContact":
Table. Table containing key/value pairs to pre-fill a new contact's details with. Supported keys include:
firstName, middleName, lastNameorganization, jobTitle, birthdayphoneticFirstName, phoneticMiddleName, phoneticLastNameprefix, suffix, nicknamephoneIphone, phoneMobile, phoneMain, phoneHome, phoneWorkfaxHome, faxWork, faxOther, pagerhomeEmail, workEmailhomePageUrl, workUrl, homeUrlfather, mother, parent, brother, sister, childfriend, spouse, partner, assistant, managerhomeStreet, homeCity, homeState, homeZip, homeCountryworkStreet, workCity, workState, workZip, workCountrysocialFacebook, socialTwitter, socialFlickr, socialLinkedIn, socialMyspace, socialSinaWeibo, socialGameCenterinstantMessagingAim, instantMessagingFacebook, instantMessagingGaduGadu, instantMessagingGoogleTalk, instantMessagingICQ, instantMessagingJabber, instantMessagingMSN, instantMessagingQQ, instantMessagingSkype, instantMessagingYahooFunction. 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.The following additional properties apply if params.option is set to "unknownContact":
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.
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.
Boolean. If set to true, the Add to Existing Contact or Create New Contact buttons will be available on the contacts overview screen.
String. Alternate name to display instead of the contact's first and last name.
String. This string is displayed below alternateName.
Table. Table containing key/value pairs to pre-fill an unknown contact's details with. Supported keys include:
firstName, middleName, lastNameorganization, jobTitle, birthdayphoneticFirstName, phoneticMiddleName, phoneticLastNameprefix, suffix, nicknamephoneIphone, phoneMobile, phoneMain, phoneHome, phoneWorkfaxHome, faxWork, faxOther, pagerhomeEmail, workEmailhomePageUrl, workUrl, homeUrlfather, mother, parent, brother, sister, childfriend, spouse, partner, assistant, managerhomeStreet, homeCity, homeState, homeZip, homeCountryworkStreet, workCity, workState, workZip, workCountrysocialFacebook, socialTwitter, socialFlickr, socialLinkedIn, socialMyspace, socialSinaWeibo, socialGameCenterinstantMessagingAim, instantMessagingFacebook, instantMessagingGaduGadu, instantMessagingGoogleTalk, instantMessagingICQ, instantMessagingJabber, instantMessagingMSN, instantMessagingQQ, instantMessagingSkype, instantMessagingYahooFunction. 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.The following data is available in the event table of the listener function when the popup is dismissed:
firstName (string)middleName (string)lastName (string)
organization (string)jobTitle (string)department (string)
birthday (string)anniversary (string)otherDate1 (string) — this key is incremented for each "other" entry, for example otherDate2
phoneticFirstName (string)phoneticMiddleName (string)phoneticLastName (string)
prefix (string)suffix (string)nickName (string)
phoneIphone (string)phoneMobile (string)phoneMain (string)phoneHome (string)phoneWork (string)phoneOther1 (string) — this key is incremented for each "other" entry, for example phoneOther2
picture (table) — contains keys filename (string) and baseDir (userdata)
faxHome (string)faxWork (string)faxOther (string)pager (string)
homeEmail (string)workEmail (string)otherEmail1 (string) — this key is incremented for each "other" entry, for example otherEmail2
homePageUrl (string)homeUrl (string)workUrl (string)otherUrl1 (string) — this key is incremented for each "other" entry, for example otherUrl2
father (string)mother (string)parent (string)brother (string)sister (string)child (string)
friend (string)spouse (string)partner (string)assistant (string)manager (string)
homeStreet (string)homeCity (string)homeState (string)homeZip (string)homeCountry (string)
workStreet (string)workCity (string)workState (string)workZip (string)workCountry (string)
otherStreet1 (string) — this key is incremented for each "other" entry, for example otherStreet2otherCity1 (string) — this key is incremented for each "other" entry, for example otherCity2otherState1 (string) — this key is incremented for each "other" entry, for example otherState2otherZip1 (string) — this key is incremented for each "other" entry, for example otherZip2otherCountry1 (string) — this key is incremented for each "other" entry, for example otherCountry2
Facebook (table) — contains username (string) and url (string) for certain servicesgamecenter (table) — contains username (string) and url (string) for certain serviceslinkedin (table) — contains username (string) and url (string) for certain servicesGoogleTalk (table) — contains username (string) and url (string) for certain servicessinaweibo (table) — contains username (string) and url (string) for certain servicesAIM (table) — contains username (string) and url (string) for certain servicesGaduGadu (table) — contains username (string) and url (string) for certain servicesSkype (table) — contains username (string) and url (string) for certain servicesJabber (table) — contains username (string) and url (string) for certain servicesflickr (table) — contains username (string) and url (string) for certain servicesmyspace (table) — contains username (string) and url (string) for certain servicestwitter (table) — contains username (string) and url (string) for certain servicesMSN (table) — contains username (string) and url (string) for certain servicesICQ (table) — contains username (string) and url (string) for certain servicesfacebook (table) — contains username (string) and url (string) for certain servicesQQ (table) — contains username (string) and url (string) for certain servicesYahoo (table) — contains username (string) and url (string) for certain services
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 )