native.showPopup()

Type Function
Library native.*
Return value Boolean
Revision Release 2024.3703
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, and Amazon App Store. If you pass in "appStore", the iTunes App Store requires the iOSAppId to be set in the options table.
  • "requestAppPermission" — Displays a popup window for requesting an app permission.
  • "activity" — This setting pertains to the Activity plugin.
  • "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 section below which corresponds to the name parameter.

mail

The following key-value pairs apply within the options table if name is set to "mail":

sms

The following key-value pairs apply within the options table if name is set to "sms":

appStore / rateApp

The following key-value pairs apply within the options table if name is set to "appStore" or "rateApp":

requestAppPermission

Currently this option is only available on Android. The following key-value pairs apply within the options table if name is set to "requestAppPermission":

activity

The name value of "activity" pertains to the Activity plugin.

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.

safariView

The name value of "safariView" pertains to the Safari View plugin.

Examples

Email Popup
-- Email popup with one file attachment
local options =
{
   to = "[email protected]",
   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
-- Email popup with multiple correspondents and attachments
local options =
{
   to = { "[email protected]", "[email protected]" },
   cc = { "[email protected]", "[email protected]" },
   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 )
SMS Popup (Simple)
local options =
{
   body = "I scored over 9000!!! Can you do better?"
}
native.showPopup( "sms", options )
SMS Popup (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",
   supportedAndroidStores = { "google", "amazon" }
}
native.showPopup( "appStore", options )
Store Details for Another App
local options =
{
   iOSAppId = "1234567890",
   androidAppPackageName = "my.other.app.",
   supportedAndroidStores = { "google", "amazon" }
}
native.showPopup( "appStore", options )
Simple App Permission Request
local options =
{
   appPermission = "Calendars"
}
native.showPopup( "requestAppPermission", options )
Critical App Permission Request
local function appPermissionsListener( event )
    for k,v in pairs( event.grantedAppPermissions ) do
        if ( v == "Camera" ) then
            print( "Camera permission granted!" )
        end
    end
end

local options =
{
    appPermission = "Camera",
    urgency = "Critical",
    listener = appPermissionsListener,
    rationaleTitle = "Camera access required",
    rationaleDescription = "Camera access is required to take photos. Re-request now?",
    settingsRedirectTitle = "Alert",
    settingsRedirectDescription = "Without the ability to take photos, this app cannot properly function. Please grant camera access within Settings."
}
native.showPopup( "requestAppPermission", options )