IMPORTANT: Per accedir als fitxer de subversion: http://acacha.org/svn (sense password). Poc a poc s'aniran migrant els enllaços. Encara però funciona el subversion de la farga però no se sap fins quan... (usuari: prova i la paraula de pas 123456)

Apache Cordova or Cordova és un framework per al desenvolupament d'aplicacions per a mòbils que permet desenvolupar apps utilitzant tecnologies web estàndard com HTML5, CSS3, i Javascript facilitant el desenvolupament multiplataforma i evitar tenir que dissenyar una aplicació per a cada plataforma nativa. Les aplicacions s'executen dins de cada plataforma utilitzant wrappers i es proporcionen APIs que compleixen amb estàndards per accedir a característiques pròpies dels dispositius com poden ser els sensors, les dades, l'estat de la xarxa, etc.

Aquest tipus d'aplicacions també són conegudes com a hybrid apps o aplicacions híbrides. Consulteu l'apartat Hybrid mobile app frameworks per conèixer altres frameworks.

Visually explained: http://www.tricedesigns.com/2012/03/22/phonegap-explained-visually/

Història

La empresa Nitobi va donar a conèixer el projecte PhoneGap l'any 2008 al iPhoneDevCamp. El projecte va tenir molt d'èxit fins al punt que va ser comprat per Adobe al 2011 fet que va provocar un canvi d'estratègia: tot el codi de PhoneGap és va pasar a la Apache Software Foundation amb el nom de Cordova que era el carrer on Nitobi tenia la seu a Vancouver. A partir d'aquest moment Apache Cordova és converteix en el motor de Phonegap com agrada explicar a la gent d'Adobe d'una forma similar a la relació que hi ha entre el motor WebKit i Chrome.

Els dos projectes són lliures amb Adobe buscant la seva font de negoci amb un projecte de creació d'aplicacions per a mòbils una plataforma cloud que proporcionarà llibreries extres de pagament per facilitar el desenvolupament d'apps. En tot cas Apache Cordova sempre serà lliure al estar sota l'auspici de la ASF amb una Apache License v2.0 [1]

Apache Cordova vs Phonegap

A very good explanation could be found at Ionic blog:

http://blog.ionic.io/what-is-cordova-phonegap/

When to use Apache cordova/Hybrid apps

Use Apache Cordova if you are:

  • a mobile developer and want to extend an application across more than one platform, without having to re-implement it with each platform's language and tool set.
  • a web developer and want to deploy a web app that's packaged for distribution in various app store portals.
  • a mobile developer interested in mixing native application components with a WebView (special browser window) that can access device-level APIs, or if you want to develop a plugin interface between native and WebView components.

Basic Components

https://www.w3.org/TR/widgets/

Apache Cordova applications rely on a common config.xml file that provides information about the app and specifies parameters affecting how it works, such as whether it responds to orientation shifts. This file adheres to the W3C's Packaged Web App, or widget, specification [2].

The application itself is implemented as a web page, by default a local file named index.html, that references whatever CSS, JavaScript, images, media files, or other resources are necessary for it to run. The app executes as a WebView within the native application wrapper, which you distribute to app stores.

The Cordova-enabled WebView may provide the application with its entire user interface. On some platforms, it can also be a component within a larger, hybrid application that mixes the WebView with native application components. (See Embedding WebViews for details.)

A plugin interface is available for Cordova and native components to communicate with each other. This enables you to invoke native code from JavaScript. Ideally, the JavaScript APIs to that native code are consistent across multiple device platforms. As of version 3.0, plugins provide bindings to standard device APIs. Third-party plugins provide additional bindings to features not necessarily available on all platforms. You can find these third-party plugins in the plugin registry and use them in your application. You can also develop your own plugins, as described in the Plugin Development Guide. Plugins may be necessary, for example, to communicate between Cordova and custom native components.

NOTA: As of version 3.0, when you create a Cordova project it does not have any plugins present. This is the new default behavior. Any plugins you desire, even the core plugins, must be explicitly added

IMPORTANT: Cordova DOES NOT provide any UI widgets or MV* frameworks. Cordova provides only the runtime in which those can execute. If you wish to use UI widgets and/or an MV* framework, you will need to select those and include them in your application yourself as third-party material. Other frameworks like Ion (see Hybrid mobile app frameworks for a list of frameworks)

Instal·lació

Requeriments

Step by Step

The pre-requirements are:

Install Cordova:

$ sudo npm install -g cordova

Create a new app

$ mkdir github 
$ cd github 
$ mkdir cordova
$ cd cordova
$ cordova create hello com.example.hello HelloWorld

Then we add platform we will support:

$ cd hello 
$ cordova platform add android

To build app:

$ cordova build

Al platforms folder for android app is created at folder platforms:

platforms/android

NOTA: You could open this folder with Android Studio as any other Android project or...

Tou can test the app in Android using Android emulator (needs a previous AVD configured):

$ cordova emulate android

Or directly on device with (you device have to be configured and detected with adb devices command):

$ cordova run android

To generate and APK:

$ cordova build android --release

File structure. Cordova architecture

  • www folder: The www folder is where you will code your HTML / JavaScript application. Open the index.html file in a browser to see the default application created by the Cordova CLI.
  • platforms folder: The platforms folder is where Cordova will build your application for different platforms (iOS, Android, etc). The contents of this folder will be automatically generated by the Cordova CLI, and you should never edit code in that directory.
  • plugins folder: Plugins are installed in the plugins directory.

Main configuration file is config.xml.

Cordova CLI

Cordova aporta una eina per línia de comandes (CLI) que us permet gestionar els vostres projectes Cordova. Vegeu

Cordova create

cordova create

Templates

ES poden crear nous projectes cordova a partir d'una plantilla de Github, NPM o una carpeta local

$ cordova create hello com.example.hello HelloWorld --template <npm-package-name>
$ cordova create hello com.example.hello HelloWorld --template <git-remote-url>
$ cordova create hello com.example.hello HelloWorld --template <path-to-template>

Per crear una nova plantilla podem utilitzar l'exemple:

https://github.com/apache/cordova-template-reference

Resources


Cordova requirements

Comprova que tinguem tot correctament configurat per a les plataformes instal·lades:

 $ cordova requirements
Requirements check results for android:
Java JDK: installed 1.8.0
Android SDK: installed true
Android target: installed android-8,android-10,android-15,android-16,android-17,android-18,android-19,android-20,android-21,android-22,android-23,android-25,Google Inc.:Google APIs:8,Google Inc.:Google APIs:10,Google Inc.:Google APIs:15,Google Inc.:Google APIs:16,Google Inc.:Google APIs:17,Google Inc.:Google APIs:18,Google Inc.:Google APIs (x86 System Image):19,Google Inc.:Google APIs:19,Google Inc.:Google APIs:21,Google Inc.:Google APIs:22,Google Inc.:Google APIs:23
Gradle: installed 

Requirements check results for browser:
Check failed for browser due to Failed to check requirements for browser platform. check_reqs module is missing for platform. Skipping it...
Error: Some of requirements check failed

Com funciona WebView

Per exemple a Android podeu veure com s'utilitza la WebView amb Android_Webview#Cordova.

Plugins

Els plugins es poden instal·lar utilitzant la comanda cordova plugin add. Exemple:

$ cordova plugin add cordova-plugin-device
Fetching plugin "cordova-plugin-device" via npm
Installing "cordova-plugin-device" for android
ANDROID_HOME=/home/sergi/Android/Sdk
JAVA_HOME=/usr/share/jdk1.8.0_121
Subproject Path: CordovaLib
...

Podeu consultar la llista de plugins instal·lats amb:

$ cordova plugin
cordova-plugin-compat 1.1.0 "Compat"
cordova-plugin-device 1.1.4 "Device"
cordova-plugin-file 4.3.1 "File"
cordova-plugin-whitelist 1.3.1 "Whitelist"

I totes les opcions de la comanda amb:

 $  cordova plugin --help

Compte! cal tenir en compte que trobareu molts exemples a Internet amb el format anterior, per exemple dels plugins device i console:

$ cordova plugin add org.apache.cordova.device
$ cordova plugin add org.apache.cordova.console

See plugins at:

https://cordova.apache.org/docs/en/4.0.0/cordova_plugins_pluginapis.md.html

You can search addtitional plugins at repo:

http://plugins.cordova.io/#/

Informació del dispositiu

El nom del plugin és :

cordova-plugin-device 

Per instal·lar el plugin executeu:

$ cordova plugin add cordova-plugin-device

Un cop instal·lat el plugin disposem d'una variable global device amb informació del dispositiu:

document.addEventListener("deviceready", onDeviceReady, false);
function onDeviceReady() {
    console.log(device.cordova);
}

Info disponible:

device.cordova
device.model
device.platform
device.uuid
device.version 
device.manufacturer
device.isVirtual
device.serial

Recursos:

Whitelist

https://taco.visualstudio.com/en-us/docs/cordova-security-whitlists/

Possiblement el plugin més important i l'únic que està activat/instal·lat de sèrie al crear un nou projecte Cordova amb la comanda cordova create. És important destacar que des de la versió 5 de Cordova ([3]) per defecte no es permet cap mena d'accés per xarxa sense la instal·lació d'algun Plugin. Aquesta política és molt restrictiva (tot a la llista negra per defecte) i per aquesta raó el plugin whitelist (llista blanca) s'instal·lar per defecte i es permeten unes mínimes (i habituals) interaccions possibles per tal de que les aplicacions Cordova siguin funcionals.

La configuració per defecte del fitxer config.xml de Cordova és:

<plugin name="cordova-plugin-whitelist" spec="1" />
<access origin="*" />
<allow-intent href="http://*/*" />
<allow-intent href="https://*/*" />
<allow-intent href="tel:*" />
<allow-intent href="sms:*" />
<allow-intent href="mailto:*" />
<allow-intent href="geo:*" />
Nota: En antigues versions de Cordova només havia access origin="*" que era una política totalment permissiva permeten totes les formes de comunicación ja sigui per XHR/Ajax, navegació, utilitzar scripts exteriors i tots tipus de recursos de xarxa

Per tal de tenir un sistema funcional però al mateix temps segur actualment hi ha 3 opcions de control:

  • access: S'utilitza l'etiqueta html <access>. Ara només controla a on la nostra aplicació pot realitzar peticions XHR (Ajax) o com accedir a altres continguts externs per Android i iOS. Ara ja no controla quan podem o no navegar a un altre domini
  • allow-navigation: S'utilitza l'etiqueta html <allow-navigation>. Permet indicar cap a quines pàgines l'aplicació podrà navegar dins del propi WebView. Si observeu per defecte no s'especifica cap URL i això és així per evitar problemes de seguretat ja que el fet de navegar cap a una web permet que aquesta web tingui accés als plugins de Cordova fet que pot implicar una escalada de privilegis al dispositiu mòbil. Per tant per defecte no és permet la navegació de cap mena i heu d'especificar els dominis de confiança amb aquesta etiqueta. Podeu afegir dominis a allow-navigation si són dominis propis sobre els que teniu control i sabeu que no pot haver-hi codi malicios o dominis de tercers que siguin de confiança.
  • allow-intent: S'utilitza l'etiqueta html <allow-intent>. S'utilitza per controlar els Android intents. Aquí cal tenir un compte un detall important. Si poseu un link html a una app Cordova veureu que el link sobre però observeu que ho fa a una aplicació externa (navegador del mòbil si esteu a Android). De fet us preguntarà amb quina aplicació voleu obrir el link. Observeu que en canvi amb la plataforma browser això no passa. No és el mateix doncs navegar que obrir una URL amb una aplicació externa (a Android això es realitza amb Intents)

Si voleu mostrar/navegar a una pàgina/domini que no sigui de confiança podeu utilitzar el plugin InAppBrowser i no cal afegir el domini a allow-navigation. Aquest plugin permet obrir/navegar a dominis sense donar accés als plugins de Cordova a aquests dominis. InAppBrowser permet la navegació a qualsevol URI i a un subconjunt limitat de intents.

Cal tenir però en compte algusn detalls depenent de la plataforma:

  • Android: suporta el ús tant de access, allow-navigation, i allow-intent. De fet els Intents són un concepte específic d'Android.
  • iOS: suporta només l'ús de access i allow-navigation. As of 6.0.0 (Cordova iOS 4.0.0) it is built into the iOS platform so a plugin is not required.
  • Windows 10: suporta allow-navigation igual que iOS i Android. Acces també es suportat però es comporta diferent ja que de sèrie amb acces Windows limita l'accés als plugins de Cordova. A Windows 10, XHR, CSS, i image access rules han d'utilitzar Content Security Policy (CSP) utilitzant connect-src en compte de llistes específiques white-list
  • Windows 8.0, 8.1, and Windows Phone 8.1 no suporten navegació a URI externes sense l'ús del plugin InAppBrowser. XHR es permès a qualsevol domini.
  • Windows Phone 8 (WP8): Soporta només access al mode antic de Cordova i per tant no hi ha suport per allow-navigation ni allow-intent.

Instal·lació (normalment no caldrà al estar definit al fitxer config.xml per defecte):

$ cordova plugin add cordova-plugin-whitelist
$ cordova prepare

Per últim indicar que Cordova es basa en:

https://www.w3.org/TR/widgets-access/

Recursos:

Cordova Navigation. Navegació from website to local content

Per qüestions de seguretat (crec TODO) no es facilita la navegació des de una pàgina web a una WebView (local content file://) i us podeu trobar amb l'error:

not allowed to load local resource file://

Quan podem necessitar aquest tipus de navegació? Per exemple per navegar a una URL externa i després tornar a l'aplicació, per exemple quan implementem el flux Oauth implicit grant. Vegeu OAuth_hybrid_apps.

Sembla ser ([4]) que pot haver diferències entre utilitzar window.open i window.location directament.

Android i configuració de la WebView:

Cal tenir en compte que només es permet l'accés a recursos locals des del sistema local vegeu setAllowFileAccess([5]) té valor true per defecte , però en canvi setAllowFileAccessFromFileURLs ([6]) esta en false per defecte.

Resources:

InAppBrowser

Llegiu abans Cordova-plugin-whitelist per entendre per a que serveix i diferenciar entre obrir pàgines a un navegador externs i dins de la WebView això com comprendre les implicacions de seguretat.

Instal·lació:

$ cordova plugin add cordova-plugin-inappbrowser

Un cop instal·lat es pot mostrar una nova URL amb:

var ref = cordova.InAppBrowser.open('http://apache.org', '_blank', 'location=yes');

Podem substituir window.open amb:

window.open = cordova.InAppBrowser.open;

És a dir que el mètode open de InAppBrowser comparteix API amb el mètode window.open de vanilla Javascript.

Es pot eliminar la sobrescritura de window.open amb:

delete window.open // Reverts the call back to it's prototype's default

I cal tenir en compte que window.open està disponible en global scope en canvi InAppBrowser només després de deviceready event.

document.addEventListener("deviceready", onDeviceReady, false);
function onDeviceReady() {
    console.log("window.open works well");
}


Vegeu una possible aplicació del Plugin amb Oauth a OAuth_hybrid_apps#InAppBrowser

Resources:

Alerts/dialogs

$ cordova plugin add cordova-plugin-dialogs

Sobrescriure els alerts per defecte:

document.addEventListener('deviceready', function () {
  if (navigator.notification) { // Override default HTML alert with native dialog
      window.alert = function (message) {
          navigator.notification.alert(
              message,    // message
              null,       // callback
              "Workshop", // title
              'OK'        // buttonName
          );
      };
  }
}, false);

Exemple alerts/dialogs natius:

07_01_usage_sample1.png

Altres mètodes:

navigator.notification.alert 
navigator.notification.confirm
navigator.notification.prompt
navigator.notification.beep

Recursos:

300ms delay on touch

Codi per activar (només onDeviceready):

 FastClick.attach(document.body);

Resources:

cordova-plugin-statusbar

Instal·lació:

$ cordova plugin add cordova-plugin-statusbar

Configuració de l'status Bar, afegir a config.xml:

<preference name="StatusBarOverlaysWebView" value="false" />
<preference name="StatusBarBackgroundColor" value="#ee6e73" />
<preference name="StatusBarStyle" value="blacktranslucent" />

Notifications

Vegeu phonegap-plugin-push i l'article Android_Push_Notifications_amb_Cordova

No confondre amb canviar els dialegs/Alerts de l'aplicació i també és important entendre la diferència entre notificacions web (API web de notificacions) i Push Notifications natives de dispositiu (per exemple les enviades amb GCM a Android)

Recursos:

GCM Android

Resources:

Vibration/Vibracions

Instal·lació:

$ cordova plugin add cordova-plugin-vibration

Codi:

document.addEventListener("deviceready", onDeviceReady, false);
function onDeviceReady() {
    console.log(navigator.vibrate);
}
navigator.vibrate,
navigator.notification.vibrate

Resources:

Hardware acceleration

Geolocation API

$ cordova plugin add cordova-plugin-geolocation

Codi exemple:

this.addLocation = function(event) {
  event.preventDefault();
  navigator.geolocation.getCurrentPosition(
      function(position) {
          alert(position.coords.latitude + ',' + position.coords.longitude);
      },
      function() {
          alert('Error getting location');
      });
  return false;
};

Resources:

Camera API

$ cordova plugin add org.apache.cordova.camera

Exemple de codi:

this.changePicture = function(event) {
  event.preventDefault();
  if (!navigator.camera) {
      alert("Camera API not supported", "Error");
      return;
  }
  var options =   {   quality: 50,
                      destinationType: Camera.DestinationType.DATA_URL,
                      sourceType: 1,      // 0:Photo Library, 1=Camera, 2=Saved Album
                      encodingType: 0     // 0=JPG 1=PNG
                  };

  navigator.camera.getPicture(
      function(imgData) {
          $('.media-object', this.$el).attr('src', "data:image/jpeg;base64,"+imgData);
      },
      function() {
          alert('Error taking picture', 'Error');
      },
      options);

  return false;
};

Resources:

Contacts API

$ cordova plugin add cordova-plugin-contacts

Exemple codi:

this.addToContacts = function(event) {
    event.preventDefault();
    console.log('addToContacts');
    if (!navigator.contacts) {
        alert("Contacts API not supported", "Error");
        return;
    }
    var contact = navigator.contacts.create();
    contact.name = {givenName: employee.firstName, familyName: employee.lastName};
    var phoneNumbers = [];
    phoneNumbers[0] = new ContactField('work', employee.officePhone, false);
    phoneNumbers[1] = new ContactField('mobile', employee.cellPhone, true);
    contact.phoneNumbers = phoneNumbers;
    contact.save();
    return false;
};

Recursos:

Android intents

Només funcionarà amb Android! solució no multiplataforma.

Com capturar intents:

http://sciencevikinglabs.com/capturing-android-intents/


Resources:

Background services

Sistema semimanual:

https://www.red-folder.com/blog/phonegap-android-background-service

Best practives

SPA Is Your Friend

First and foremost - your Cordova applications should adopt the SPA (Single Page Application) design. Loosely defined, a SPA is a client-side application that is run from one request of a web page. The user loads an initial set of resources (HTML, CSS, and JavaScript) and further updates (showing a new view, loading data) is done via AJAX. SPAs are commonly used for more complex client-side applications. GMail is a great example of this. After you load GMail, mail views, editing, and organization are all done by updating the DOM instead of actually leaving the current page to load a completely new one.

Using a SPA can help you organize your application in a more efficient manner, but it also has specific benefits for Cordova applications. A Cordova application must wait for the deviceready event to fire before any plugins may be used. If you do not use a SPA, and your user clicks to go from one page to another, you will have to wait for deviceready to fire again before you make use of a plugin. This is easy to forget as your application gets larger.

Even if you choose not to use Cordova, creating a mobile application without using a single page architecture will have serious performance implications. This is because navigating between pages will require scripts, assets, etc., to be reloaded. Even if these assets are cached, there will still be performance issues.

Examples of SPA libraries you can use in your Cordova applications are:

FAQ

Can you use PHP/ASP/JSF/Java/.NET with PhoneGap?

PhoneGap/Apache Cordova application may only use HTML, CSS, and JavaScript. However, you can make use of network protocols (XmlHTTPRequest, Web Sockets, etc) to easily communicate with backend services written in any language. This allows your PhoneGap app to remotely access existing business processes while the device is connected to the Internet.

See also:

http://www.genbetadev.com/php/ya-se-puede-usar-php-para-desarrollar-en-android-e-ios

SPA i múltiples pàgines

Múltiples pàgines i handleOpenURL

handleOpenURL

Format-detection

Format-detection meta:

<meta name="format-detection" content="telephone=no">

Serveix perquè els números de telèfon o qualsevol cosa que si pareixi no es converteixin en link per a fer una trucada.

Content Security Policy

Vegeu Content Security Policy

Cordova release, crear apk signat i alineat per a publicar en explotació (Google Play)

Hi ha opció:

$ cordova build android --release 

Però no firma ni signa apk

Millor crear un fitxer anomenat ant.properties a carpeta platforms/android/ i el contingut :

key.store=/path/to/keystore/release_key_name.keystore
key.alias=alias_name

I executar:

 $ cordova build android --release 

El fitxer es crearà a:

platforms/android/ant-build/app_name-release.apk

Altre opció?:

$ cordova build android --release -- --keystore="..\android.keystore" --storePassword=android --alias=mykeyalias=mykey

Recursos:


Troubleshooting

A partir de la versió 4.0.0 de Cordova 4.0.0 podem arribar a tindre dificultats per a connectar-nos mitjançant http a l'API. Al debuggar mitjançant chrome://inspect/#devices podrem observar el següent error:

ERROR 404 Not Found

La raó per la qual no ens funcionen les peticions és perque per defecte se permeten només les navegacions cap a les URLs file://.

La solució de l'error és afegir el següent plugin:

$ ionic plugin add https://github.com/apache/cordova-plugin-whitelist

o afegir al config.xml els protocols que ens interessen mitjançant la etiqueta <allow-navigation/> :

<allow-navigation href="http://*/*" />
<allow-navigation href="https://*/*" />
<allow-navigation href="data:*" />
  • Recursos:

Vegeu també

Enllaços externs