July 25, 2016

Guide – App Development from your Website

 Information for web developers – app deployment methodologies and controlling apps from your website’s JavaScript.

Contents:

 

Introduction

Welcome to AppUrSite Hybrid+ app development for web designers and developers. An AppUrSite app consists of an AppUrSite WordPress plugin and two Hybrid+ apps (iOS & Android) configured for your specific web domain. This document provides an overview of the information you need to begin adding native device functionality to your app via code written in the AppUrSite WordPress plugin.

 

AppUrSite Plugin Orientation

The plugin installed (or to be installed) on your server contains the following folder structure and files:

Appursite/

appursite.html – Includes a key for a specific web domain to work with the app (do not touch).

appursite.php – Runs on the server.

includes/js/

appursite_web.js – Loads in all clients (browser or app) and…

  1. If app, loads the appursite_app.js file and other plugin files.
  2. If browser, opens page in app if app exists on device.

appursite_app.js – This is where you, the web developer, will introduce the majority of your custom app functionality. Although, you will be able to add some custom functionality in other JavaScript files wrapped in appropriate if statements. For further information, reference the in line documentation in this file.

 

Client/Server Relationship

Appursite is set up such that a Hybrid+ app always knows it is an app and therefore requests from the server the JavaScript files it requires to implement the native app functionality you desire to add to your mobile website. This means that the server does not necessarily need to know or care whether it is dealing with an app client or a web client.

From experience, we can tell you that making the server code “client-agnostic” is the safest way to go, simply because different web-hosts handle server-side caching differently, and can therefore potentially mislead the server as to the type of client it is serving. Case in point: Appursite’s technology will always set a cookie on the client side indicating what type of app is talking to the server, but if your web host opts to return a cached page to non-logged-in clients and thereby ignore cookies (such as a lot of top tier web-hosts do for optimization purposes), the server might determine that it is responding to a browser client instead of an app client.

The “is_appursite()” function exists in order to allow the server to know what type of client it is dealing with in case you find it necessary for the server to hand an app client something different than a web client, such as a different block of HTML or an extra CSS file. We just caution that if you do this, you must know your hosting environment and how they handle server-side caching and cookies. Also remember that JavaScript relevant to an app client should be written in the “appursite_app.js” file or otherwise called as a separate JavaScript file as directed by the code contained in the “appursite_web.js” file.

  • An app will always return a cookie called “hybrid_plus_app” set equal to the app platform (“ios” or “android”).
  • An app will always append a query string to every url it calls, such as “?hyplus=ios” or “?x=y&hyplus=android”.

In the event your host does ignore cookies under certain conditions, Appursite also appends a query string as above. With most hosts, you can instruct them to NOT return a cached page for any url containing this query string, thus overcoming this limitation while still allowing non-logged-in browser-client users to receive cached pages (and avoid heated arguments with your host concerning the importance of optimization). However, be aware that these hosts (again from experience) can on occasion mysteriously drop the exclusion to caching and cause you some support headaches.

All in all, the safest (and most optimized) bet is to remain client-agnostic on the server side, and if the app client does require something different from the server, find other creative solutions. For instance, make use of AJAX to have the app client request an extra block of HTML (see the appursite_example_ajax_call() function), or request an additional CSS file via the same mechanism we use to request the app-centric javascript files within “appursite_web.js”.

 

Developing App Functionality using JavaScript Libraries

The following list of Cordova plugins are built into the apps. Hybrid+ apps create the unique ability for you to control these plugins through JavaScript on the website. The links provided for each plugin take you to the developer documentation. Look for the JavaScript instructions for direction on how to build simple JavaScript commands to control device/OS functionality.

Cordova Device Plugin – This plugin defines a global device object, which describes the device’s hardware and software. Although the object is in the global scope, it is not available until after the deviceready event. The following properties are available.

  • cordova
  • model
  • platform
  • uuid
  • version

https://www.npmjs.com/package/cordova-plugin-device

Cordova Device Orientation Plugin – This plugin provides access to the device’s compass. The compass is a sensor that detects the direction or heading that the device is pointed, typically from the top of the device. It measures the heading in degrees from 0 to 359.99, where 0 is north.

https://www.npmjs.com/package/cordova-plugin-device-orientation

Cordova Device Motion Plugin – This plugin provides access to the device’s accelerometer. The accelerometer is a motion sensor that detects the change (delta) in movement relative to the current device orientation, in three dimensions along the x, y, and z axis.

https://www.npmjs.com/package/cordova-plugin-device-motion

Cordova Geolocation Plugin – This plugin provides information about the device’s location, such as latitude and longitude. Common sources of location information include Global Positioning System (GPS) and location inferred from network signals such as IP address, RFID, WiFi and Bluetooth MAC addresses, and GSM/CDMA cell IDs. There is no guarantee that the API returns the device’s actual location.

https://www.npmjs.com/package/cordova-plugin-geolocation

Cordova InAppBrowser Plugin – This plugin provides a web browser view that displays when calling cordova.InAppBrowser.open().

https://www.npmjs.com/package/cordova-plugin-inappbrowser

Cordova Media Plugin – This plugin provides the ability to record and play back audio files on a device.

https://www.npmjs.com/package/cordova-plugin-media

Cordova Media Capture Plugin – This plugin provides access to the device’s audio, image, and video capture capabilities.

https://www.npmjs.com/package/cordova-plugin-media-capture

Cordova Notification Plugin – This plugin provides access to some native dialog UI elements via a global navigator.notification object. AppUrSite has implemented a function you can use to send notifications to devices using this plugin. Below is an excerpt from the AppUrSite documentation contained within the appursite_app.js file located within the AppUrSite webstie plugin.

The Hybrid+ App environment allows for a more robust ‘alert’ than a browser client. Here we are maintaining the ability to call a traditional web browser alert from within an app via ‘web_alert’ (not that you ever would), while capturing any existing alerts in your code base to display them with a native-style alert. By default, this will replace the title of the alert from being the full URL (which often makes the title longer than the message!) to the word “Alert”. You’d hate to have an alert fire in an app that indicates a website is underneath…it just looks sloppy.

Because you can overload the native web browser “alert”, you can begin to code ANY alerts in your website codebase with additional parameters to support nicer app-centric alerts when the site is running in an app, without negatively affecting the browser client…

https://www.npmjs.com/package/cordova-plugin-dialogs

Cordova Camera Plugin – This plugin defines a global navigator.camera object, which provides an API for taking pictures and for choosing images from the system’s image library. The following functions are available.

  • camera.getPicture(success, fail, options)
  • CameraOptions
  • CameraPopoverHandle
  • CameraPopoverOptions
  • camera.cleanup

https://www.npmjs.com/package/cordova-plugin-camera

Cordova Contacts Plugin – This plugin provides access to the device contacts database.

Methods

  • contacts.create
  • contacts.find
  • contacts.pickContact

Objects

  • Contact
  • ContactName
  • ContactField
  • ContactAddress
  • ContactOrganization
  • ContactFindOptions
  • ContactError
  • ContactFieldType

https://www.npmjs.com/package/cordova-plugin-contacts

Cordova File System Plugin – This plugin implements a File API allowing read/write access to files residing on the device. Read the detailed documentation at the link below.

https://www.npmjs.com/package/cordova-plugin-file

Cordova File Transfer Plugin – This plugin allows you to upload and download files. Read the detailed documentation at the link below.

https://www.npmjs.com/package/cordova-plugin-file-transfer

Cordova Globalization Plugin – This plugin obtains information and performs operations specific to the user’s locale, language, and timezone. Note the difference between locale and language: locale controls how numbers, dates, and times are displayed for a region, while language determines what language text appears as, independently of locale settings. Often developers use locale to set both settings, but there is no reason a user couldn’t set her language to “English” but locale to “French”, so that text is displayed in English but dates, times, etc., are displayed as they are in France. Unfortunately, most mobile platforms currently do not make a distinction between these settings.

https://www.npmjs.com/package/cordova-plugin-globalization

Cordova Network Information Plugin – This plugin provides information about the device’s cellular and wifi connection, and whether the device has an internet connection. AppUrSite utilizes this plugin by displaying a “No Internet Connection” page when an internet connection is not available.

https://www.npmjs.com/package/cordova-plugin-network-information

Cordova Screen Orientation Plugin – This plugin can be used to set/lock the screen orientation.

https://www.npmjs.com/package/cordova-plugin-screen-orientation

Cordova Vibration Plugin – This plugin provides a way to vibrate the device.

https://www.npmjs.com/package/cordova-plugin-vibration

SpinnerDialog – This plugin initiates a spinner graphic typically implemented between page loads and other transitions requiring the user to wait. AppUrSite apps utilize this plugin to display a spinner between page loads. You may choose to implement this for other transitions within your app.

https://github.com/Paldom/ETrade-Client-NG/tree/master/plugins/hu.dpal.phonegap.plugins.SpinnerDialog

Cordova StatusBar Plugin – The StatusBar object provides some functions to customize the iOS and Android StatusBar. AppUrSite provides functions in the appursite_app.js file contained within the AppUrSite website plugin to control the StatusBar Plugin.

https://www.npmjs.com/package/cordova-plugin-statusbar

Phonegap Plugin Push – Register and receive push notifications. Unlike most of the other plugins listed here, this plugin requires a complex implementation that includes php, data tables and other detailed requirements. AppUrSite simplifies the implementation of push notifications by making a plugin available for your website. Our website plugin makes it possible to broadcast push notifications to all devices or if your site has users, you can create push notifications for specific users or groups of users. If you do not have this plugin, contact AppUrSite for more information.

https://www.npmjs.com/package/phonegap-plugin-push

Cordova Battery Plugin – This plugin provides an implementation of the Battery Status Events API. The following three events are available.

  • batterystatus
  • batterycritical
  • batterylow

https://www.npmjs.com/package/cordova-plugin-battery-status

 

Below are Plugins to be aware of that are utilized by default in the apps:

 

Cordova Whitelist Plugin – This plugin implements a whitelist policy for navigating the application webview on Cordova 4.0. This plugin implements a Content Security Policy that is configured to be very open. If you encounter problems loading specific content in the app, look into the settings for this plugin found at the link below.

https://www.npmjs.com/package/cordova-plugin-whitelist

Cordova Console Plugin – This plugin is meant to ensure that console.log() is as useful as it can be. It adds additional function for iOS, Ubuntu, Windows Phone 8, and Windows. If you are happy with how console.log() works for you, then you probably don’t need this plugin.

https://www.npmjs.com/package/cordova-plugin-console

Cordova Splashscreen Plugin – This plugin displays and hides a splash screen during application launch.

https://www.npmjs.com/package/cordova-plugin-splashscreen

Cordova Webintent – This plugin is used internally to support App Links and/or Google App Indexing.

https://github.com/initsogar/cordova-webintent

Cordova AppVersion plugin – Reads the version of your app from the target build settings. We have already provided this as “localStorage.hybridPlus_version”.

https://www.npmjs.com/package/cordova-plugin-app-version