Making applications with Simplicité is good! Having him on his mobile is even better! In order to meet this request we have written a short guide so that you can have your application in the palm of your hand wherever you go! Follow the guide!

By following this short guide you will be able to:

  • Available on Play store and Apple store.
  • Embed the responsive website and support HTML5/CSS3.
  • Allows device and desktop to receive notifications.
  • and server back-end to post messages (to users, or groups or all users).

In order to deploy our application we will use Cordova®.

Cordova® is an open source framework developed by the Apache Foundation that allows you to create applications for different platforms. This framework also allows applications to be deployed on the most popular mobile systems such as Android and IOS. This guide will cover Android deployment, the version for IOS will follow soon.

Cordova®

Prerequisites :

 Java JDK 8

Environment variables :

 

  • JAVA_HOME :  JDK root (ex C:\dev\java\jdk1.8)
  • ANDROID_HOME :root of your android SDK (ex C:\dev\android\sdk)
  • GRADLE_USER_HOME :change the gradle home repository without special characters in path (ex C:\dev\gradle)
  • Add to PATH
    • the studio gradle (ex C:\dev\android\studio\gradle\gradle-4.6\bin)
    • the JDK bin directory (ex C:\dev\java\jdk1.8\bin)

 

Install cordova CLI

npm install -g cordova`
cordova --version

Pour IOS il est nécessaire d’installer un plugin qui nécessitera de télécharger Xcode sur votre machine.

npm i -g xcode

Create your application

 

cordova create myproject com.simplicite.mobile.myproject MyProjectName
cd myproject

Add platforms and plugins

  • cordova platform add android
  • cordova plugin add cordova-plugin-whitelist
  • cordova plugin add cordova-plugin-inappbrowser
  • cordova plugin add cordova-plugin-network-information
  • cordova plugin add cordova-plugin-dialogs
  • cordova plugin add cordova-plugin-exit

 Android test

 

Create/launch one emulator in Android Studio then:

cordova build android
cordova emulate android

Starts on your device in debug mode :

cordova run android

Integrate the hybrid app

Open your project directory and customize your application:

  • www/img/logo.png is used on the default splash screen.
  • Tous les res/icon/android and res/icon/ios with your logos.
  • Change the default www/js/index.js
  • Init Firebase plugin to register / receive notifications on each device.
  • Launch the webapp into a  inAppBrowser

Script www/js/index.js

 

(function() {

    var url = 'https://myproject.dev.simplicite.io';
    var fireBaseToken, win, winReady;

    // Call the UI firebase handler
    function exec(d) {
        d = typeof(d)=="string" ? d : JSON.stringify(d);
        winReady && win.executeScript({ code: 'window.$ui.firebase(' + d + ');' });
    }

    // Notify server with firebase token after login
    function syncFirebaseToken(token) {
        token = token || fireBaseToken;
        if (token) {
            fireBaseToken = token;
            exec({ token:token });
        }
    }

    function error(e) { console.error(error); }

    // Firebase events
    function firebase() {
        // Notification : cordova-plugin-firebase
        var pfb = window.FirebasePlugin;
        if (pfb) {
            console.log("[FirebasePlugin] init");
            //pfb.grantPermission();
            pfb.getToken(syncFirebaseToken, error);
            pfb.onTokenRefresh(syncFirebaseToken, error);
            pfb.onNotificationOpen(function(m) {
                console.log("[FirebasePlugin] onNotificationOpen " + JSON.stringify(m));
                exec(m);
            }, error);
        }
    }

    // Load Simplicite URL
    function open() {
        // In-app browser
        win = cordova.InAppBrowser.open(url + "?inapp=true", '_blank', 'location=no');
        win.addEventListener('loadstop', function() {
            winReady = true;
            syncFirebaseToken();
        });
        //win.addEventListener('exit', function() {});
    }

    // Cordova loaded
    function init() {
        var parentElement = document.getElementById('deviceready');
        var listeningElement = parentElement.querySelector('.listening');
        var receivedElement = parentElement.querySelector('.received');
        listeningElement.setAttribute('style', 'display:none;');
        receivedElement.setAttribute('style', 'display:block;');
    }
    function ready() {
        init();
        firebase();
        open();        
    }
    document.addEventListener("deviceready", ready, false);
})();

Icones pour les applications

 

 

  • Import your icons into res/icon folders
  • Change config.xml to bind all sizes as follow :
    <platform name="android">
            ...
        <icon density="ldpi" src="res/icon/android/icon-36-ldpi.png" />
        <icon density="mdpi" src="res/icon/android/icon-48-mdpi.png" />
        <icon density="hdpi" src="res/icon/android/icon-72-hdpi.png" />
        <icon density="xhdpi" src="res/icon/android/icon-96-xhdpi.png" />
    </platform>
    <platform name="ios">
            ...
        <icon height="114" src="res/icon/ios/icon-57-2x.png" width="114" />
        <icon height="57" src="res/icon/ios/icon-57.png" width="57" />
        <icon height="144" src="res/icon/ios/icon-72-2x.png" width="144" />
        <icon height="72" src="res/icon/ios/icon-72.png" width="72" />
    </platform>

Firebase configuration

Firebase is a program published by Google that allows you to send notifications directly to devices and browsers (Chrome). Very convenient to notify we will see here how to configure the tool.

The platform will use different parameters:

  • FIREBASE : to activate the service on platform and UI.
  • FIREBASE_PRIVATE_KEY : private setup to init the service on server side.
  • FIREBASE_TOKENS : used to store each user devices (desktop, mobile, tablet…).
  • FIREBASE_CONFIG : public configuration on Web client-side.
  • FIREBASE_LIBS : public firebase libs to load on client-side.
  • FIREBASE_VAPID_KEY : public key for firebase authentication.

Register your application on Firebase :

  1. Create your Firebase account https://firebase.google.com
  2. Access to the console to add your project, ex SimpliciteMobileMyProject

Add to project the application for Androïd

 

  • With your cordova package name ( ex. simplicite.mobile.myproject ).
  • Generate and download the google-services.json  in your local project root, it is required to compile the firebase plugin.
  • and copy google-services.json into platforms/android/app in case of build error.

Add the firebase plugin

Notification https://github.com/arnesson/cordova-plugin-firebase

cordova plugin add cordova-plugin-firebase

cordova run android

Send a message with the console

 

  • Use the google console to access the Cloud Messaging section of your project
  • Compose a message.

https://console.firebase.google.com/u/0/project/simplicitemobilemyproject/notification/compose

  • Verify your device.

 

Back-end integration

 

Set system parameter Firebase = yes  to activate the service. On UI $ui.firebase wrap all Firebase message :

  • to register user and device on server-side (see FIREBASE_TOKENS on each user).
  • to send a notification to users (unique, groups or all).

On Server-side service, see  GoogleFireBaseTools :

  • you must generate first your Service Account Key on console

https://console.firebase.google.com/u/0/project/simplicitemobilemyproject/settings/serviceaccounts/adminsdk

then place your strongly private credentials in the parameter FIREBASE_PRIVATE_KEY on server-side :

{
  "type": "service_account",
  "project_id": "simplicitemobilemyproject",
  "private_key_id": "41d94061ba24e55a0b74b5xxxxxxxxxxxxxx",
  "private_key": "-----BEGIN PRIVATE KEY-----\nxxxxxxxxxxx\n-----END PRIVATE KEY-----\n",
  "client_email": "firebase-adminsdk-xxxxxx@simplicitemobilemyproject.iam.gserviceaccount.com",
  "client_id": "10898538xxxxxxxxxxxxx",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://oauth2.googleapis.com/token",
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
  "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/firebase-adminsdk-xxxxxx%40simplicitemobilemyproject.iam.gserviceaccount.com"
}

Front-end integration (desktop)

 

To receive message on webapp, the browser needs 2 parameters:

 

  1. Add a public system param FIREBASE_LIBS
["https://www.gstatic.com/firebasejs/5.5.3/firebase-app.js"
,"https://www.gstatic.com/firebasejs/5.5.3/firebase-messaging.js"]
  1. Add a public system param FIREBASE_CONFIG to init firebase on client-side:
{
"apiKey": "AIzaSyB...",
"authDomain": "simplicitemobilemyproject.firebaseapp.com",
"databaseURL": "https://simplicitemobilemyproject.firebaseio.com",
"projectId": "simplicitemobilemyproject",
"storageBucket": "simplicitemobilemyproject.appspot.com",
"messagingSenderId": "134..."
}

  1. Add a public system param FIREBASE_VAPID_KEY to authent client

Get the public VAPID key from key-pair on Firebase console / Configuration web:

BIDDmZgk5QSFd7Bf1sf2yfUrfi...

note firebase is not loaded in webapp:

  • If FIREBASE_CONFIG is not set on platform
  • If webapp is embedded into mobile inAppBrowser : Cordova includes the firebase plugin and events outside the site.

Unit test

 

JSON Message :


"data":{
    "title": "hello",
    "body": "world",
    "priority": "high | normal | low"
}

To send one notification to a device:

curl --header "Authorization: key=<cloud messaging server key>" --header "Content-type: application/json" -d '{"to":"<device token>", "data":{"title":"hello","body":"world","icon":"notification_icon"}}' https://fcm.googleapis.com/fcm/send

Get the server key on your Firebase console / Project Setup / Cloud Messaging / Server key Token (use the long one, the short key is deprecated)

  • Get the device token stored in user’s FIREBASE_TOKENS (or logged in browser console).

Icones de notifications

 

  • iOS does not support customization and use the default app icon
  • Android supports icon resources referenced in notification:
  1. Generate your mono-color/transparent icons : https://romannurik.github.io/AndroidAssetStudio/icons-notification.html
  2. Importez-les dans votre projet res/icon/android
  3. Add resources in config.xml to copy them indrawable as notification_icon
    
    <platform name="android">
    ...
        <resource-file src="res/icon/android/drawable-mdpi/notification_icon.png" target="app/src/main/res/drawable-mdpi/notification_icon.png" />
        <resource-file src="res/icon/android/drawable-hdpi/notification_icon.png" target="app/src/main/res/drawable-hdpi/notification_icon.png" />
        <resource-file src="res/icon/android/drawable-xhdpi/notification_icon.png" target="app/src/main/res/drawable-xhdpi/notification_icon.png" />
        <resource-file src="res/icon/android/drawable-xxhdpi/notification_icon.png" target="app/src/main/res/drawable-xxhdpi/notification_icon.png" />
        <resource-file src="res/icon/android/drawable-xxxhdpi/notification_icon.png" target="app/src/main/res/drawable-xxxhdpi/notification_icon.png" />
    </platform>

See also :

 

Deploy on Google Play Store

Assuming your application is working on debug mode on your mobile device, you can push your signed APK on the play store.

Build a release APK

cordova build --release android

The unsigned APK is generated in your android directory myproject/platforms/android/app/build/outputs/apk/release/app-release-unsigned.apk

 

Sign your APK file

Create a keystore with your company informations :

 

cordova build android --release -- --keystore="path/to/keystore" --storePassword=xxxx --alias=key0 --password=xxxx

The signed APK is generated in your android directory

myproject/platforms/android/app/build/outputs/apk/release/app-release.apk

 

Upload the APK with the play-store console

 

You will have to change the version each time you deliver an new APK :

  • in root files config.xml and package.json
  • rebuild the release

See Google documentation.  https://support.google.com/googleplay/android-developer#topic=3450769

Process is quite long at the very first time:

  • Sign all confidentiality, brief, class PEGI 3, tax free…
  • Create the application, upload and validate your APK
  • Create a testing group
  • Publish in test mode: not visible on public store but here : https://play.google.com/apps/testing/com.simplicite.mobile.myproject
  • Promote to production when ready to use : https://play.google.com/store/apps/details?id=com.simplicite.mobile.mobile.myproject

Congrats if you are still alive at this stage!

La version IOS arrive prochainement … 🙂

Limites connues

 

  • Google OAuth2 ne fonctionne pas dans le navigateur inAppBrowser pour des raisons de sécurité (uniquement via les navigateurs natifs Chrome ou Safari).
  • W3C navigator.mediaDevices n’est pas encore supporté par inAppBrowser (certaines autorisations CAMERA sont manquantes).