native.showPopup()

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 )

mail

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

• to — Single string or an array of strings where each string is an email address of a recipient.
• cc — Single string or an array of strings where each string is an email address of a cc'd recipient.
• bcc — Single string or an array of strings where each string is an email address of a bcc'd recipient.
• attachment — 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.
• body — String for the main body of the email.
• isBodyHtml — Boolean indicating whether the email is HTML. By default, plain text is assumed.
• subject — String for the subject of the email.

sms

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

• to — Single string or an array of strings where each string is a phone number of the recipient.
• body — String for the SMS message content.

appStore / rateApp

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

• iOSAppId — String ID assigned to the app by the iTunes App Store.
• tvOSAppId — String If specified, this will be used on tvOS instead of iOSAppId.
• androidAppPackageName — String indicating the unique package name 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, Solar2D 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.
• supportedAndroidStores — 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 Solar2D knows which app store to display the popup from. This is especially needed while testing and debugging the app. Currently, string names of "amazon" and "google" are supported.

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":

• appPermission — Single string or an array of strings where each string is an app permission to request. Valid options include the following platform-agnostic types:

  • "BodySensors" — Corresponds to the SENSORS permission group on Android. Only available on Android devices running version 4.4W and above.

  • "Calendars" — Corresponds to the CALENDAR permission group on Android.

  • "Camera" — Corresponds to the CAMERA permission group on Android.

  • "Contacts" — Corresponds to the CONTACTS permission group on Android.

  • "Location" — Corresponds to the LOCATION permission group on Android.

  • "Microphone" — Corresponds to the MICROPHONE permission group on Android.

  • "Phone" — Corresponds to the PHONE permission group on Android.

  • "SMS" — Corresponds to the SMS permission group on Android.

  • "Storage" — Corresponds to the STORAGE permission group on Android.

  On Android, this can also be the name of anything in the usesPermissions table of build.settings, such as "android.permission.READ_SMS" or "com.android.voicemail.permission.ADD_VOICEMAIL". The full name of an Android permission group such as "android.permission-group.STORAGE" or "android.permission-group.PHONE" is also valid.

  To properly use app permissions on Android, you'll need to add at least one of the Android permissions corresponding to a platform-agnostic type to the usesPermissions table of build.settings. See Table 1 of Android's dangerous permission group documentation for more information on which Android permissions correspond with which platform-agnostic types.

• urgency — String representing how urgent this permission request is to running the app. Must be one of the following values:

  • "Low" — This is the default urgency level. It indicates that something minor is dependent on the app permission, but most features of the app can be experienced without this permission. These requests simply ask for the permission and, if the request is denied, no additional effort is made to change the user's decision. For example, the "Location" permission is not a mandatory aspect of using the camera.

  • "Normal" — A worthwhile feature of this app is dependent on the app permission. While the app can work without the permission, a significant part of the experience will be missing. With "Normal" urgency, if the user denies the app permission request, the app permission rationale dialog will be presented to explain the reasoning behind the permission request. For example, access to "Contacts" for a social media app is useful for sending friend requests to your contacts, but the app can function without it.

  • "Critical" — The basic functionality of this app is dependent on the app permission and getting access is necessary. For example, "Camera" access is critical to a QR code reader. This urgency level has all of the same behaviors as "Normal", but if the "Never Ask Again" option is selected, upon the next occasion this permission is requested, the settings redirect dialog will appear which prompts the user to grant the permission in Settings.

• listener — Listener which supports basic popup events. In addition, for "requestAppPermission", it supports the following properties:

  • event.grantedAppPermissions — Table containing the string representation of each app permission that was just granted to the app. On Android, the usesPermission names are used for any app permissions that don't have a platform-agnostic representation. Because of this, table contents can be a mix of platform-agnostic types and Android usesPermission names.

  • event.deniedAppPermissions — Table containing the string representation of each app permission that was just requested and denied to the app. On Android, the usesPermission names are used for any app permissions that don't have a platform-agnostic representation. Because of this, table contents can be a mix of platform-agnostic types and Android usesPermission names.

  • event.neverAskAgain — Boolean value which corresponds to the "Never Ask Again" checkbox that's presented if an app permission is requested multiple times. This value is on a per-permission basis, so it may be true for one permission but false for another.

• rationaleTitle — String containing the title for the app permission rationale dialog. If urgency is set to "Low", this option will be ignored.

• rationaleDescription — String containing the description for the app permission rationale dialog. If urgency is set to "Low", this option will be ignored.

• settingsRedirectTitle — String containing the title for the settings redirect dialog. This option only applies if urgency is set to "Critical".

• settingsRedirectDescription — String containing the description for the settings redirect dialog. This option only applies if urgency is set to "Critical".

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 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 )

-- 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 )

local options =
{
   body = "I scored over 9000!!! Can you do better?"
}
native.showPopup( "sms", options )

local options =
{
   to = { "1234567890", "9876543210" },
   body = "I scored over 9000!!! Can you do better?"
}
native.showPopup( "sms", options )

local options =
{
   iOSAppId = "1234567890",
   supportedAndroidStores = { "google", "amazon" }
}
native.showPopup( "appStore", options )

local options =
{
   iOSAppId = "1234567890",
   androidAppPackageName = "my.other.app.",
   supportedAndroidStores = { "google", "amazon" }
}
native.showPopup( "appStore", options )

local options =
{
   appPermission = "Calendars"
}
native.showPopup( "requestAppPermission", options )

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 )