native.showPopup()

Type Function
Library native.*
Return value Boolean
Revision Current Public Release (2014.2511)
Keywords email, sms, text message, store, social, showPopup
See also native.canShowPopup()

Overview

Displays the operating system's default popup window for a specified service. Displaying this popup suspends the app on both iOS and Android.

This function returns true or false indicating whether the popup was displayed or not. If it returns false, then the popup was not available or the service was not available for the device.

Syntax

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

String. The string name of the popup to be shown. It can be one of the following:

  • "mail" — Displays a popup window for composing an email.

  • "sms" — Displays a popup window for composing an SMS message.

  • "appStore" — Displays a popup window from the app store that the application was downloaded from. It will display the app's details such as the summary, an option to purchase (if not already done), and an option to write a review. This can be used to display the details of the currently running app or another app that you wish to advertise to the user. Currently, these app stores are supported: iTunes App Store, Google Play, Amazon App Store, and Nook App Store. If you pass in "appStore", the iTunes App Store and the Nook App Store require the iOSAppId or nookAppEAN to be set in the options table.

  • "social" — This setting pertains to the Social plugin.

  • "addressBook" — This setting pertains to the Address Book plugin.

  • "quickLook" — This setting pertains to the Quick Look plugin.

options (optional)

Table. A table that specifies the optional properties for the popup — see the next section for details.

Options Reference

Valid properties in the options table depend upon the value specified for name.

mail

The following options apply if name is set to "mail":

options.to

String or Array. Single string or an array of strings. Each string is an email address of a recipient.

options.cc

String or Array. Single string or an array of strings. Each string is an email address of a cc'd recipient.

options.bcc

String or Array. Single string or an array of strings. Each string is an email address of a bcc'd recipient.

options.attachment

Table. Table in the form { baseDir=, filename= [, type=] }. For the type property, use an appropriate MIME type such as "image/png", "image/jpeg", "application/pdf", etc. To send multiple attachments, you must create an array of these tables.

options.body

String. String for the main body of the email.

options.isBodyHtml

Boolean. Boolean indicating whether the email is HTML. By default, plain text is assumed.

options.subject

String. String for the subject of the email.

sms

The following options apply if name is set to "sms":

options.to

String or Array. Single string or an array of strings. Each string is a phone number of the recipient.

options.body

String. String for the SMS message content.

appStore

The following options apply if name is set to "appStore":

options.iOSAppId

String. String ID assigned to the app by the iTunes App Store.

options.nookAppEAN

String. String ID assigned to the app by the Nook App Store.

options.androidAppPackageName

String. The unique package name string of the Android app to be displayed by the Google Play or Amazon app stores. This property is optional. If you do not provide a package name, Corona will use the currently running app's package name by default. You should only set this if you want to display the app store details of another app.

options.supportedAndroidStores

Array. An array of strings indicating which app stores are supported on Android. This is needed in case the app was not installed by an app store so that Corona knows which app store to display the popup from. This is especially needed while testing and debugging the app. The following string names are supported: "amazon", "google", and "nook".

social

The name value of "social" pertains to the Social plugin.

addressBook

The name value of "addressBook" pertains to the Address Book plugin.

quickLook

The name value of "quickLook" pertains to the Quick Look plugin.

Examples

Email Popup with one File Attachment
local options =
{
   to = "john.doe@somewhere.com",
   subject = "My High Score",
   body = "I scored over 9000!!! Can you do better?",
   attachment = { baseDir=system.DocumentsDirectory, filename="Screenshot.png", type="image/png" },
}
native.showPopup( "mail", options )
HTML Email Popup with Multiple Correspondents and Attachments
local options =
{
   to = { "john.doe@somewhere.com", "jane.doe@somewhere.com" },
   cc = { "john.smith@somewhere.com", "jane.smith@somewhere.com" },
   subject = "My High Score",
   isBodyHtml = true,
   body = "<html><body>I scored over <b>9000</b>!!! Can you do better?</body></html>",
   attachment =
   {
      { baseDir=system.DocumentsDirectory, filename="Screenshot.png", type="image/png" },
      { baseDir=system.ResourceDirectory, filename="MyLogo.png", type="image/png" },
   },
}
native.showPopup( "mail", options )
Simple SMS Popup
local options =
{
   body = "I scored over 9000!!! Can you do better?"
}
native.showPopup( "sms", options )
SMS Popup with Multiple Recipients
local options =
{
   to = { "1234567890", "9876543210" },
   body = "I scored over 9000!!! Can you do better?"
}
native.showPopup( "sms", options )
Store Details
local options =
{
   iOSAppId = "1234567890",
   nookAppEAN = "0987654321",
   supportedAndroidStores = { "google", "amazon", "nook" },
}
native.showPopup( "appStore", options )
Store Details for Another App
local options =
{
   iOSAppId = "1234567890",
   nookAppEAN = "0987654321",
   androidAppPackageName = "my.other.app.",
   supportedAndroidStores = { "google", "amazon", "nook" },
}
native.showPopup( "appStore", options )