Custom Plug-ins

Adding custom Cordova plug-ins

Introduction

Appery.io enables you to import Cordova plug-ins for use in apps without the need for configuring additional source files.

Custom Cordova plug-ins are supported in the following app library versions:

  • Ionic 4/5 library version 1.0 or higher.
  • jQuery Mobile library version 5.0 or higher.

📘

App Version

Before you update to a new library version it's important ​that you create an app version so you can go back to it in case something doesn't work.

Importing Cordova Plug-ins from GitHub

Before the plug-in can be used in your app, you need to import it to Appery.io. You can choose one of the two ways to do it:

📘

Latest Plug-in Version

We strongly recommend downloading the latest plug-in version.

👍

Important notice

Be informed that when creating an app with Cordova plug-ins it is important that the needed plug-in be imported before you proceed with the app UI or create it from a backup.

Facebook Plug-in Example

Please check how to import a custom Cordova plug-in on the example of the Facebook Cordova plug-in.

1. Importing from ZIP bundle

  • Go to the plug-in GitHub page, for example, the official Facebook plugin in Apache Cordova/PhoneGap.
  • Here, click the green Code button and select the Download ZIP option. ZIP archive with the plug-in source files will be downloaded to your drive:
  • From the Appery.io dashboard, navigate to Resources > Cordova plugins and click the Import Cordova plugin button.
  • Under the ZIP bundle tab, click Choose file.
  • Select the ZIP archive you have just downloaded and click Import Plugin:

From now on, when you open your projects you’ll see this plug-in among the imported plug-ins:

2. Importing with Git URL

  • Go to the plug-in GitHub page, for example, the official Facebook plugin in Apache Cordova/PhoneGap.
  • Click the green Code button.
  • Click the button next to the text field to copy the plug-in URL to the clipboard:
  • From the Appery.io dashboard, navigate to Resources > Cordova plugins and click the Import Cordova plugin button.
  • Go to the From Git tab.
  • Paste the copied URL into the Repository URL field and enter master as the Repository branch name, as shown on the screenshot below:
  • Click Import plugin.

Once imported, the plug-in is added to the account Cordova plugins list. Now, as you need to use the imported plug-in for some particular project, in the app, open App settings > Cordova plugins > Imported Cordova plugins, enable it, and click the SAVE button at the top:

👍

Important Note: Adding Dependencies in Ionic 4 projects

For correct work in Ionic 4 projects, the imported plug-ins must be correctly defined under the MODULE tab:

  1. First of all, go to Project > App settings > Npm modules and add a new Dependency, for example, @ionic-native/social-sharing of the needed version.
  2. Unfold the Pages folder and choose the app page.
  3. Click the MODULE tab of the app page. In the Imports section, type in import { SocialSharing } from '@ionic-native/social-sharing/ngx'; as an example.
  4. Then, scroll down to the NgModule Settings > Providers section and type SocialSharing into the text field.
  5. Save the changes.

📘

Custom Plug-in Permissions

A custom Cordova plug-in permission can be managed by selecting the Permissions tab when viewing plug-in details.

More Examples of Using Custom Plug-ins in Appery.io

Below are some examples of how custom plug-ins can be used in Appery.io projects.

  • Ionic 5 Calendar plug-in Sample App
    In this sample app tutorial, we will show how to build an Ionic 5 app, where you can use the Cordova Calendar plug-in. This plug-in allows viewing and adding events to the mobile device calendar.

  • Ionic 4 Calendar plug-in Example
    In this tutorial, we will show how to build an Ionic 4 app, where you can use Cordova Calendar plug-in. This plug-in allows viewing and adding events to the mobile device calendar.

  • Ionic 4 Document Scanner plug-in Example
    The tutorial that shows how to build an Ionic 4 app, where you can use the Cordova Document Scanner plug-in.

  • Ionic 4 File Upload App Example
    This tutorial describes how to create an Ionic 4 app that can upload files from the device to the Firebase project storage using the Cordova plug-ins.

  • Ionic 4 Social Sharing plug-in Example
    This tutorial demonstrates how to build an Ionic 4 app, where you can use Cordova Social Sharing plug-in to share links, images, and text messages out of the app on social platforms or by email.

  • Toast plug-in Example Example
    Check here for instructions on how to import and configure the Toast Cordova plug-in in an Appery.io app.

  • Pollfish plug-in Example
    The blog post on how to add a Polish survey into your app: Appery.io + Pollfish: How to Integrate a Pollfish Survey into Your App.

  • BitPay App Example
    The sample app demonstrating how to add secure Bitcoin payments to your Appery.io mobile app with the BitPay Cordova SDK can be found here.

🚧

Testing Apps with Custom Plug-in

To test the app, you must build the binary and launch the app on your device.

Passing Parameters to Plug-ins

Some Cordova plug-ins require initialization parameters to work properly. The phonegap-facebook-plugin, for example, requires APP_ID and APP_NAME variables to be specified.

Go to App settings > Cordova plugins and click the Options button next to the plug-in. A modal window opens, where the necessary options can be added and specified. Click Save options.

Custom Cordova plugin parameters.Custom Cordova plugin parameters.

Custom Cordova plugin parameters.

📘

Option Button Color

The Options buttons will change to dark blue when at least one parameter is set.

Stuff You Should Know

When working with plug-in parameters:

  • You can add any number of key/value pairs to any Cordova plug-in (core or custom).
  • Key/values options can be changed/deleted at any time.
  • Options for unselected plug-ins can be managed as well.
  • Keys should be unique to one plug-in (subject to validation).
  • For parameter names, the following symbols are allowed: all digits, letters, and an underscore or minus sign (subject to validation).
  • Empty keys/values are not allowed.
  • Parameter names are validated for duplication.

Quirks

There are several important issues to note when using Cordova plug-ins:

  • Uploading files larger than 40 Mb is not allowed.
  • Before uploading plug-in .zip archive make sure it contains only plugin code (without any other files).
  • Plug-ins do not work for Appery.io Tester.
  • Cordova and Cordova plug-ins can’t be updated with the Automatic update feature.
  • When creating an app from the backup, re-adding custom plug-ins to the backup application is required as they are lost while building a backup.
  • Cordova plug-ins are not included under the Source tab in the Project view.

More Help Resources

Here is a great resource to help you learn Cordova basics:

Help with Custom Plug-ins

Our support team is not able to provide help or debug assistance with every 3rd party custom Cordova plug-in since it's impossible to be familiar with all of the plug-ins out there.

There are many reasons why a custom plug-in might not work:

  • Incorrect configuration.
  • Incorrect version support.
  • Bugs in the plug-in (broken or outdated).

Our Support Pack services do include help with custom Cordova plug-ins. Please consider purchasing one of the packs if you need help with a custom Cordova plug-in.