Home → Documentation → jQuery Mobile → Using native device features (PhoneGap)
If you find any errors, typos or have general feedback, select the text and click CTRL+ALT+ENTER.

Introduction

Every app that you create in Appery.io includes Apache Cordova (PhoneGap). Apache Cordova provides two main capabilities:

  1. Wraps the mobile web app inside a native wrapper.
  2. Allows you to access native device features such as camera, contacts and more.

Appery.io allows you to build a binary for Android and iOS that includes PhoneGap. The binary file that you download is ready to be published to the app market.

Quickstart

If you are new to using native features, please try these quickstart tutorials:

Pre-installed Cordova plugins

Appery.io provides a set of pre-installed plugins that available immediately once the new project has been created:

Appery.io supports and updates its list of pre-installed Cordova plugins as developers release new ones. To review the up-to-day core Cordova plugins that are available for your app by default, go to: Resources > Cordova plugins > General > Core Cordova plugins.

Apache Cordova (PhoneGap)

When you create a new app in Appery.io, the app includes the Apache Cordova library. This means you can use any of the JavaScript APIs provided by PhoneGap.

For example, if you want the device to beep, you can add this code and run it on button click:

Since this is a native API call, you need to install the app on the device to test it. You can also use the Appery.io Mobile Tester to test the app.

Learn more about testing via the link.

To check the current PhoneGap version included in the Appery.io builder, go to Project > App Settings > External resources.

Adding native components

While you can use any PhoneGap JavaScript API, Appery.io also comes with a number of APIs available as preconfigured native services (components). The following services are available:

  • Camera
  • Barcode scanner
  • Geolocation
  • Contacts

To add a native component to an app, go to Project > Create new > Services, then select one of the native components and click “Create Service”:CreateNewService

Once the service has been added, it will be listed under the Services folder:
ServicesFolder

If you open the service, you will notice that the service has the same structure as a regular REST service. The service has Request and Response tabs, but the values in them are predefined (using the Camera service):

The Request tab:RequestTab

The Response tab:ResponseTab

Once a native service has been added to the app, it can be added to one or more pages. Adding a native service to a page is very similar to adding a REST service to a page:

  1. Open DATA view.
  2. For the datasource, select Device > CameraService and click “Add”:

AddDatasource

Once the service has been added to the page, click “Mapping” to map the service to the page.

Learn more about mapping by clicking the link.

Using the StatusBar plugin (iOS)

Appery.io provides a way to handle the visibility of the status bar on iOS devices. The StatusBar plugin is included in all Appery.io apps by default, so you can use it from scratch without any additional actions. To hide the status bar on iOS devices, use the hide() method:

The status bar can be shown by using the show() method:

Using iOS In-App Purchase plugin

Tutorial from the forum.

Adding 3rd party plugins

Introduction

Appery.io enables you to import Cordova plug-ins for use in apps without needing to configure additional source files.

This functionality will be added beginning with the new external library version 3.0 (JQM)/ 1.0 (AngularJS) only.

So, when switching from 3.0 to other libraries, all manual changes will be deleted and the added plug-ins will be deleted too – therefore, a project version should be created before downgrading libraries.

Core Cordova plug-ins

Go to Resources > Cordova plug-ins > Core Cordova plug-ins to see the list of the preconfigured plug-ins available from Cordova. To get information on the plug-in, select it:SelectPlugin

In this view, managing permissions is disabled since the core Cordova plug-ins are available to the entire team.

You may decide not to enable some of them (or unselect them all by clicking the corresponding button) in your project in order to decrease the app size. Only enabled (checked) plug-ins will be included into the binary application and be used for any target device type in events, services, etc.: Project > App settings > Cordova plug-ins.

Importing Cordova plug-ins

In the following examples, you’ll learn how to import 3rd party Cordova plug-ins, that are not on the Core Cordova plug-ins list. You’ll learn to import them, configure them by passing parameters, and then launch them.

Importing Toast plug-in

In the following example, you’ll learn how to import 3rd party Cordova plug-in in the example of the Toast-PhoneGap plug-in.

  1. Go to the plug-in page: https://github.com/EddyVerbruggen/Toast-PhoneGap-Plugin and click Download ZIP to start downloading and then save the file to your drive:
    >

    It’s highly recommended that you download the latest stable version available.

  2. In the Builder, switch to Resources > Cordova Plug-ins and click Import Cordova plug-in, then: Choose file, locate the downloaded file (Toast-PhoneGap-Plugin-master.zip) and click Import plug-in The plug-in appears under Cordova plug-ins:
  3. To manage permissions to the imported Cordova plug-ins, go to: Resources > Cordova plug-ins, select the plug-in under Cordova plug-ins and switch to the Permissions tab:ManagingPermissions

Managing permissions to the imported Cordova plug-ins is similar to managing permissions under Apps > Permissions.

The plug-in also appears in App settings > Cordova plug-ins > Imported Cordova plug-ins in all your projects. To enable the plug-in for the current project, check the appropriate box to add it to the binary application:

Use the corresponding buttons to select/unselect all the imported Cordova plug-ins to the build.

Click the Refresh button if the plug-in has been imported/deleted with the editor open.

Basically, that’s all you need to do in plug-in configuring. Now you can use its API as described in appropriate docs. For example, you can execute the following code on button click to show the toast:

We’ve prepared a little more extended app (AngularJS & Ionic) with Toast plug-in enabled . In this app, you can modify your toasts’s message, duration, and position via UI. It looks as following:

You can create this app from the backup ( ToastCordova_backup) to see how it’s built (but make sure you have imported Toast plug-in before).

To create an app from the backup:

  1. Click “Create new app”.
  2. Type an app name.
  3. Click “From backup” and select the project backup file.
  4. Click “Create”.

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

Importing Facebook plug-in

In the following example, you’ll learn how to import the Facebook Plugin.

  1. First, go to the plug-in page: https://github.com/Wizcorp/phonegap-facebook-plugin and click Download ZIP to start downloading it and then save the file to your drive:

    It’s highly recommended that you download the latest stable version available.

    In the Builder, switch to Resources > Cordova Plug-ins and click Import Cordova plug-in, then: Choose file, locate the downloaded file and click Import plug-in The plug-in appears under Cordova plug-ins:

    To manage permissions to the imported Cordova plug-ins, go to: Resources > Cordova plug-ins, select the plug-in under Cordova plug-ins and switch to the Permissions tab:ManagingPermissions

    Managing permissions to the imported Cordova plug-ins is similar to managing permissions under Apps > Permissions.

    The plug-in also appears in App settings > Cordova plug-ins > Imported Cordova plug-ins in all your projects. To enable the plug-in for the current project, check the appropriate box to add it to the binary application:

    Use the corresponding buttons to select/unselect all the imported Cordova plug-ins to the build.

    Click the Refresh button if the plug-in has been imported/deleted with the editor open.

    Passing parameters to plug-ins

    Some Cordova plug-ins require initial parameters.

    The phonegap-facebook-plug-in, for example, requires APP_ID and APP_NAME variables to be specified. Read here about the details.

    To do it, first download the plug-in, then import it (see above), and then go to App settings > Cordova plug-ins 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:

    The Options buttons have different styles depending on which options have been set.

    The selected options can be viewed by hovering the mouse over the Options button.

    Basics:

    • You can add any number of key/value pairs to any Cordova plug-in (core or custom).
    • Key/values options can be changed/deleted 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 when importing and using 3rd party Cordova plug-ins:

    • You can upload a plug-in file size up to 20Mb.
    • Before uploading plugin .zip archive make sure it contains only plug-in code (without any other files).
    • 3rd party plug-ins are not included in  the Appery.io Tester app. You can still test the custom plug-ins APIs when you install the app on the device.
    • Cordova and Cordova plug-ins can’t be updated with the Autoupdate feature.
    • When creating an app from the backup, re-adding custom plug-ins to the backup application is required as they are included in the backup file.
    • Cordova plug-ins are not included under the Source tab in Project view.

    More help resources

    More help resources are links to the blog, our YouTube channel and other web sites.