To extend the native functionality exposed by the PhoneGap native-app container, PhoneGap Build supports most PhoneGap or Cordova plugins.
Plugins need to be implemented differently for each platform, and may not be supported across all PhoneGap platforms. If you're deploying across multiple platforms, ensure that the experience degrades gracefully for users who do not have the plugin available.
There are two steps to including a plugin in your project:
Importing the native code
To import the native code into your PhoneGap Build project, you will need to add the correct
<plugin> or deprecated
<gap:plugin> tag to your config.xml file.
If you omit the
version) tag of a npm or PhoneGap Build plugin, your app will always be built with the latest version of the plugin. It will be updated automatically the next time you update your application code after a plugin is updated, which may cause unexpected behaviour. For more info on plugin versioning, click here.
If source is not present then the default value for this attribute is
git depending if it can auto-detect a git backed repo format. For instance the plugin lines below all reference the same plugin in the npm repository.
<plugin name="com.phonegap.plugins.example" spec="~1" /> <plugin name="com.phonegap.plugins.example" spec="~1" source="npm" />
spec attribute is a git location then the source is defaulted to "git". The lines below will reference the same plugin.
<plugin spec="https://github.com/apache/cordova-plugin-file.git#4.1.0" /> <plugin spec="https://github.com/apache/cordova-plugin-file.git#4.1.0" source="git" />
To include a plugin from the PhoneGap Build repository specify
pgb in the source attribute.
<plugin name="example-plugin" source="pgb" spec="~1" />
The param fragments are handled identically regardless of the source of the plugin.
Plugin Version / Location
Here is the most simplistic way of using a versioned plugin. The
spec attribute is the recommended way to specify the version.
spec is used so as to be compatibile with the Cordova CLI, which uses a
spec attribute to describe the version or location of the plugin.
<plugin name="cordova-plugin-example" spec="2.2.1" />
PhoneGap Build also supports
You can use the tilde
~ operator to specify fuzzy versions, this will ensure that you have the latest version of a plugin with the same major version.
For example, you could replace the tag above with:
<plugin name="cordova-plugin-example" spec="~2" />
which would load the latest 2.x version, but not anything with a different major/initial version number.
The following version tag:
<plugin name="com.phonegap.plugins.example" spec="~2.2" />
would load the latest 2.x version so long as x is greater or equal to 2.
And finally, this version tag:
<plugin name="com.phonegap.plugins.example" spec="~2.2.3" />
would load the latest 2.2.x version so long as x is greater or equal to 3.
Plugins may require configuration information to be present; this can be done with adding children to the
<plugin name="com.phonegap.plugins.example"> <param name="APIKey" value="12345678" /> <param name="APISecret" value="12345678" /> </plugin>
Make sure to check the documentation of the plugin to see if parameters are necessary.
Here is a config.xml that includes the Barcode Scanner plugin from npm as an example:
<?xml version="1.0" encoding="UTF-8" ?> <widget xmlns = "http://www.w3.org/ns/widgets" id = "com.phonegap.example" versionCode = "10" version = "1.0.0" > <!-- versionCode is optional and Android only --> <name>PhoneGap Example</name> <description> An example for phonegap build docs. </description> <author href="https://build.phonegap.com" email="email@example.com"> Hardeep Shoker </author> <!-- We'll include the Barcode plugin as an example --> <plugin name="phonegap-plugin-barcodescanner" /> </widget>
If a plugin utilizes the
<script src="cordova.js"></script> <script src="barcodescanner.js"></script>
Whether the script tag is required or not, do not include the actual plugin files in the zip or repository which you submit to PhoneGap Build. These files will be injected by PhoneGap Build, and including them may cause problems.