Android Dependency Integration

Background

When Corona originally opened up the Corona Marketplace to accept content made by third parties, plugin developers could upload any .jar files needed to run their plugin. This resulted in plugins being submitted that would include versions of the Android Support Libraries or Google Play Services. The version of these .jar files would often be the latest version available when the plugin was initially developed, but they were not typically updated when newer versions of the plugin were released.

Essentially, with different versions of libraries floating around inside of plugins, incompatibilities would occur between a plugin needing, for instance, Google Play Services version 8.4 and another plugin needing Google Play Services version 4.2.

Dependency Plugins

In Corona, dependency plugins are special plugins that address version incompatibilities between dependencies which multiple plugins may have. They contain all of the resources for the latest version of a particular library that Corona supports, plus any additional resources to aid in integration and proper usage of a library.

If your project depends on a common Android library like the Android Support Libraries or Google Play Services, you’ll need to include a dependency plugin to incorporate that library into your plugin submission. This is to ensure compatibility with other plugins that may be dependent on these libraries.

The following table outlines which libraries are supported by Corona as dependency plugins. While developing your plugin that meets the above criteria, you should test it against the library version encapsulated in a dependency plugin.

compile 'com.android.support:[COMPONENT_NAME]:[VERSION_NUMBER]'

compile 'com.google.android.gms:play-services-[COMPONENT_NAME]:[VERSION_NUMBER]'

Base Logic Layer

The shared.google.play.services.base dependency plugin also includes a base logic layer that will check if the environment on the device is safe for using Google Play Services and attempt to resolve any issues with using the Google Play Services .apk. This is to follow Google’s guidelines on ensuring devices have the Google Play Services APK. Resolution attempts are made by presenting either an alert or a notification with context about the issue and how to resolve it. From an alert, the end user would then tap a button and be taken somewhere else on their device to resolve the problem. From a notification, tapping on it will launch the app and present an alert with similar context.

<meta-data android:name="usesGooglePlayServicesComponent[PascalCase_NAME_OF_COMPONENT]" android:value="true" />

<meta-data android:name="usesGooglePlayServicesComponentAds" android:value="true" />

Including Dependency Plugins

To include a dependency plugin when submitting your plugin, add an entry to the coronaManifest → dependencies table of your plugin’s android/metadata.lua:

local metadata =
{
    plugin =
    {
        -- ...
    },
    coronaManifest = {
        dependencies = {
            ["shared.google.play.services.ads"] = "com.coronalabs",
        },
    },
}

return metadata

Testing Against Dependencies

Most dependency plugins simply wrap the distribution of a library accessible from the Android SDK Manager. In these cases, simply including the correct version of the library in the dependencies block of the plugin’s build.gradle (Module: plugin) file is sufficient for testing. For example, a plugin that depends on the CardView library can be accurately tested by adding compile 'com.android.support:cardview-v7:27.1.1' to the dependencies block of the build.gradle (Module: plugin) file.

Other dependency plugins may require additional resources to test against. Any dependency plugin that falls in this category will have an entry in the tarball of plugins provided in the release files of Solar2D Native. For a dependency plugin with this requirement, be sure to:

• Include the .jar file with the name of the dependency plugin. For example, the shared.google.play.services.base dependency plugin contains a shared.google.play.services.base.jar file which should be included in your project.

• Merge the contents of the manifest table of metadata.lua into your project’s AndroidManifest.xml. The parts that need to be merged in should have a comment identifying them as part of the dependency plugin’s package name, for instance -- For share-google-play-services-base package. However, any XML block designated for a different package like -- From play-services-basement package does not need to be added manually — these parts will be included in the compiled app when you add compile 'com.google.android.gms:play-services-base:15.0.1' to the dependencies block of your build.gradle (Module: app) file.

• Add any resources for the dependency plugin’s package into your project. If the dependency plugin contains multiple packages inside the resources folder, look for the package.txt file containing the dependency plugin’s package name and add the contents of the res folder to your project’s res folder.

Dependency Plugin Chaining

Just as your plugin may rely upon a dependency plugin, a dependency plugin itself may depend upon other dependency plugins. The following flow chart illustrates the chaining between dependency plugins:

Dependency Plugins and Permissions

When using a dependency plugin, some permissions may be automatically added to your app. The following table illustrates which permissions are added for which dependency plugins.