native.showPopup()

Type Function
Library native.*
Return value Boolean
Revision Current Public Release (2014.2511)
Keywords email, sms, text message, store, show popup
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.

  • "twitter" — Displays a native Twitter popup. Available for iOS only.

  • "social" — This option pertains to the Social plugin. For further details, please refer to the Implementing Facebook guide.

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

  • "quickLook" — This option 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".

twitter

The following options apply if name is set to "twitter". This popup is only available on iOS because Apple offers native support via TWTweetComposeViewController.

options.image

Table. Table in the form { baseDir=, filename= } of the image you wish to post.

options.message

String. String that pre-populates the tweet.

options.listener

Listener. Listener function which supports popup events.

options.url

String or Array. Single string or an array of strings. Each string is a URL to post.

social

This name value pertains to the Social plugin. For further details, please refer to the Implementing Facebook guide.

addressBook

This name value pertains to the Address Book plugin.

quickLook

This name value pertains to the Quick Look plugin.

Enterprise

Unlike Corona SDK, the Twitter popup is not baked into Corona Enterprise. Thus, you must add the corresponding plugin to your iOS Xcode project in order to access the Twitter popup. Specifically, you should add the static library located at: CoronaEnterprise/Plugins/native-popup-twitter/ios/libnative-popup-twitter.a

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 )