Advanced Build Settings

Device Capabilities

If you wish to limit your iOS app to devices with specific capabilities, you can include the optional UIRequiredDeviceCapabilities key within the iphone → plist table. The value of this key should be a table containing specific keys matching Apple's documentation. For example:

settings =
{
    iphone =
    {
        plist =
        {
            UIRequiredDeviceCapabilities =
            {
                ["gyroscope"] = true,
            },
        },
    },
}

When including a specific key within the UIRequiredDeviceCapabilities table, its value is expected to be a boolean with this logic:

• true — Devices must have the associated feature in order to run the app.
• false — Devices must not have the associated feature in order to run the app.

PNG Processing

If you need to circumvent PNG file processing (pngcrush) at build time, you can include the skipPNGCrush key with a value of true. This key should be specified outside of the plist table but inside the iphone table:

settings =
{
    iphone =
    {
        plist =
        {

        },
        skipPNGCrush = true,
    },
}

Minimum SDK Version

Providing a minimum SDK version with the minSdkVersion key value allows you to exclude your app from being installed on devices with older versions of the Android OS. It corresponds to the minSdkVersion item detailed here. This setting is invisible to users.

settings =
{
    android =
    {
        minSdkVersion = "16",
    },
}

Android TV

If you are deploying an app to Android TV, you should include the supportsTV key with a value of true. This will make the app available to Android TV devices via purchase through Google Play.

In addition, you can set the isGame key with a value of true to categorize the app under the games section of Google Play. If this key is omitted or set to false, the app will be categorized under the apps section.

settings =
{
    android =
    {
        supportsTV = true,
        isGame = true,
    },
}

Screen Support

The optional supportsScreens table specifies/limits which screens an Android app supports. See the Android documentation for detailed descriptions and more options.

settings =
{
    android =
    {
        supportsScreens =
        {
            smallScreens  = true,
            normalScreens = true,
            largeScreens  = true,
            xlargeScreens = false,
            requiresSmallestWidthDp = 320,
        },
    },
}

Disabling File Access

By default, other apps are granted read-only access to your app's files via an Android content:// URL. This is required to attach your app's files to e-mails, post photos via the social plugin, or open your files via the system.openURL() function. If you want to block all access to your app's files, set the following in the build.settings file:

settings =
{
    android =
    {
        allowAppsReadOnlyAccessToFiles = false,
    },
}

Large Heap

You can request that the Android OS provides your app with more heap memory in Java by adding the largeHeap key with a value of true. For example, it may raise the max heap size on a particular device from 32 MB to 256 MB. This parameter might be a viable option if your app is triggering out-of-memory exceptions on low-end devices.

settings =
{
    android =
    {
        largeHeap = true,
    },
}

Android Directives

The following specialized directives are available for Solar2D-built Android apps:

• strings — This directive enables the creation of a strings.xml file in the .apk.

settings =
{
    android =
    {
        strings =
        {
            permdesc = "Custom permission description",
            permlabel = "custom-permission-Label",
        },
    },
}

• permissions — This directive enables the creation of custom Android permissions.

settings =
{
    android =
    {
        permissions =
        {
            {
                name = ".PERMISSION1",
                description = "@string/permdesc",
                icon = "@mipmap/icon",
                label = "@string/permlabel",
                permissionGroup = "android.permission-group.COST_MONEY",
                protectionLevel = "normal",
            },
        },
    },
}

• manifestChildElements — This directive adds XML elements to the manifest element of AndroidManifest.xml.

settings =
{
    android =
    {
        manifestChildElements = 
        {
            -- Array of strings
            [[
            <uses-configuration android:reqFiveWayNav="true" />
            ]],
        },
    },
}

• applicationChildElements — This directive adds XML elements to the application element of AndroidManifest.xml.

settings =
{
    android =
    {
        applicationChildElements =
        {
            -- Array of strings
            [[
            <activity android:name="com.example.MyActivity"
                android:configChanges="keyboard|keyboardHidden"/>
            ]],
        },
    },
}

• apkFiles — This directive causes files to be copied from the project directory to the root of the .apk file, preserving any directory hierarchy. In the following example, google-play-services.json is copied to the root of the .apk and res/raw/mypage.html is copied to res/raw. The file paths are always relative to the base directory of the project.

settings =
{
    android =
    {
        apkFiles =
        {
            "google-play-services.json",
            "res/raw/mypage.html",
        },
    },
}

• coronaActivityFlags — This directive allows attributes to be added to the com.ansca.corona.CoronaActivity activity definition in the app's AndroidManifest.xml. Activity attributes are documented here.

settings =
{
    android =
    {
        coronaActivityFlags =
        {
            resizeableActivity = true,
            persistableMode = "persistRootOnly",
        },
    },
}