native.showPopup()

Type Function
Library native.*
Return value Boolean
Revision Current Public Release (2014.2189)
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.

Passing in "mail" or "sms" will display a popup window for composing an email or SMS message respectively.

Passing in "appStore" will display 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. Only the following app stores are supported — a popup window will not be displayed for other app stores.

Gotchas

If you pass in "appStore", the iTunes App Store and the Nook App Store require the iOSAppId and nookAppEAN to be set in the options table. Other app stores do not require any additional information.

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", "sms", or "appStore".

options (optional)

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

Options Reference

The options table includes optional properties for the specific popup type.

"mail"

For the "mail" popup, the following properties are supported:

  • options.to is a single string or an array of strings. Each string is an email address of a recipient.
  • options.cc is a single string or an array of strings. Each string is an email address of a cc'd recipient.
  • options.bcc is a single string or an array of strings. Each string is an email address of a bcc'd recipient.
  • options.attachment is a table of the form { baseDir=, filename= [, type=] }. For the 'type' property, use an appropriate MIME type such as "image". To send multiple attachments, you must create an array of these tables.
  • options.body is a string for the main body of the email.
  • options.isBodyHtml is a boolean indicating whether the email is HTML. By default, plain text is assumed.
  • options.subject is a string.
"sms"

For the "sms" popup, the following properties are supported:

  • options.to is a single string or an array of strings. Each string is a phone number of the recipient.
  • options.body is a string for the main body of the email.
"appStore"

For the "appStore" popup, the following properties are supported:

  • options.iOSAppId is a string ID assigned to the app by the iTunes App Store.
  • options.nookAppEAN is a string ID assigned to the app by the Nook App Store.
  • options.androidAppPackageName is the unique package name string of the Android app to be displayed by the Google Play, Amazon, or Samsung app stores. This property is optional. If you do not provide a package name, then 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 is 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", "nook", "samsung".
"twitter"

This popup is only available on iOS because Apple offers native OS support via TWTweetComposeViewController.

For the "twitter" popup, the following properties are supported.

  • options.image is a table of the form { baseDir=, filename= } to the image you wish to post.
  • options.message is a string that prepopulates the message.
  • options.listener is a listener that supports popup events.
  • options.url is a string for the url you wish to post. Alternatively, this can be an array of url strings.

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" },
}
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" },
      { baseDir=system.ResourceDirectory, filename="MyLogo.png", type="image" },
   },
}
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", "samsung", "amazon", "nook" },
}
native.showPopup( "appStore", options )
Store Details for Another App
local options =
{
   iOSAppId = "1234567890",
   nookAppEAN = "0987654321",
   androidAppPackageName = "my.other.app.",
   supportedAndroidStores = { "google", "samsung", "amazon", "nook" },
}
native.showPopup( "appStore", options )