Introduction
Every app that you create in Appery.io includes Apache Cordova (PhoneGap). Apache Cordova provides two main capabilities:
- Wraps the mobile web app inside a native wrapper.
- 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:
- Using the camera
- Showing the device location on a map (Geolocation)
- Using the barcode scanner
- Using the contacts component
- Using the InAppBrowser API
- Using the Accelerometer API
- Using the Google Analytics API
Pre-installed Cordova plugins
Appery.io provides a set of pre-installed plugins that available immediately once the new project has been created:
- com.adobe.plugins.GAPlugin
- com.phonegap.plugins.barcodescanner
- com.phonegap.plugins.pushnotification (Android. JQM projects with libraries version lower than 3.0)
- com.phonegap.phonegap-plugin-push (Android. All Angular projects and JQM projects with libraries version 3.0)
- org.apache.cordova.battery-status
- org.apache.cordova.camera
- org.apache.cordova.console (iOS)
- org.apache.cordova.contacts
- org.apache.cordova.device
- org.apache.cordova.device-motion
- org.apache.cordova.device-orientation
- org.apache.cordova.dialogs
- org.apache.cordova.file
- org.apache.cordova.file-transfer
- org.apache.cordova.geolocation
- org.apache.cordova.globalization
- org.apache.cordova.inappbrowser
- org.apache.cordova.media
- org.apache.cordova.media-capture
- org.apache.cordova.network-information
- org.apache.cordova.plugins.PushNotification (iOS)
- org.apache.cordova.splashscreen
- org.apache.cordova.statusbar (iOS)
- org.apache.cordova.vibration
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:
1 |
navigator.notification.beep(2); |
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”:
Once the service has been added, it will be listed under the Services
folder:
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):
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:
- Open
DATA
view. - For the datasource, select
Device > CameraService
and click “Add”:
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:
1 |
StatusBar.hide(); |
The status bar can be shown by using the show()
method:
1 |
StatusBar.show(); |
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:
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.
- 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.
- In the Builder, switch to
Resources > Cordova Plug-ins
and clickImport Cordova plug-in
, then:Choose file
, locate the downloaded file (Toast-PhoneGap-Plugin-master.zip
) and clickImport plug-in
The plug-in appears underCordova plug-ins
: - To manage permissions to the imported Cordova plug-ins, go to:
Resources > Cordova
plug-ins, select the plug-in underCordova plug-ins
and switch to thePermissions
tab:
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:
1 2 3 4 5 6 7 8 9 10 11 |
window.plugins.toast.showWithOptions({ message: 'Hi there!', duration: 'short', position: 'top' }, function(a) { console.log('toast success: ' + a); }, function(b) { alert('toast error: ' + b); }); |
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:
- Click “Create new app”.
- Type an app name.
- Click “From backup” and select the project backup file.
- 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.
- 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 clickImport Cordova plug-in
, then:Choose file
, locate the downloaded file and clickImport plug-in
The plug-in appears underCordova plug-ins
:
To manage permissions to the imported Cordova plug-ins, go to:
Resources > Cordova
plug-ins, select the plug-in underCordova plug-ins
and switch to thePermissions
tab: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, requiresAPP_ID
andAPP_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 theOptions
button next to the plug-in. A modal window opens, where the necessary options can be added and specified: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 inProject
view.
More help resources
More help resources are links to the blog, our YouTube channel and other web sites.