Introduction

While message flows are the ideal way to create input scenarios in Rogerthat, visualising data through messaging is quite cumbersome. Therefore developers are able to build HTML5 applications and host them via a service running in the Rogerthat app (OUR CITY APP & Rogerthat Enterprise also support this of course).

The technique is similar compared to creating a branding with the exception that the HTML5 entry file needs to be called app.html instead of branding.html

On top of what developers are used to use in HTML5 development Rogerthat comes two built-in javascript libraries that provide context to the user and the service they are running in and provide a way to perform reliable communication with the backend of a service developed in Rogerthat.

A nice example of a HTML5 app that visualises meeting room schedules can be downloaded here.

rogerthat.js, a library that provides context

The rogerthat.js library provides context to HTML5 app hosted in a Rogerthat service. The library is pre-packaged with the Rogerthat app, so developers do not need to package it themselves with their app.


In order to use this library, you need to load rogerthat/rogerthat-1.0.js

Example:

<script src="rogerthat/rogerthat-1.0.js" type="text/javascript"></script>

rogerthat.user

Rogerthat user data has the following format:

{
    "user": {
        "name": "John Doe",
        "account": "john.doe@foo.com",
        "avatarUrl": "https://rogerth.at/unauthenticated/mobi/cached/avatar/4824964683268096",
        "language": "pt_BR",
        "data": {"xmpp_username": "john", "xmpp_password": "doe"}
    }
}

To retrieve or put Rogerthat user data in your javascript, you can use the following functions:

  • rogerthat.user.name: retrieve the user name
  • rogerthat.user.account: retrieve the user account
  • rogerthat.user.avatarUrl: retrieve the user avatar
  • rogerthat.user.language: retrieve the user language.
    format: [ISO 639-1 language code]_[ISO 3166-2 region code]
  • rogerthat.user.data: retrieve the user data
  • rogerthat.user.put(): save all you have put in user data before

Example:

var name = rogerthat.user.name;
var account = rogerthat.user.account;
var avatar = rogerthat.user.avatarUrl;
var data = rogerthat.user.data;
rogerthat.user.data.xmpp_username = john;
rogerthat.user.data.xmpp_password = doe;
rogerthat.user.put();

rogerthat.service

Rogerthat service data have the following format:

{
    "service": {
        "name": "Service identity 1",
        "account": "s1@foo.com/i1",
        "data": {"xmpp_room": "chatroom1"}
    }
}

To retrieve or put Rogerthat service data in your javascript, you can use the following functions:

  • rogerthat.service.name: retrieve service name
  • rogerthat.service.account: retrieve the service account
  • rogerthat.service.data: retrieve the service data
  • rogerthat.service.getBeaconsInReach(function(beacons){}): list beacons which are in reach
var name = rogerthat.service.name;
var account = rogerthat.sevice.account;
var data = rogerthat.service.data;
var xmmpRoom = rogerthat.service.data.xmmp_room;
rogerthat.service.getBeaconInReach(function(beacons){
    console.log(beacons);
}, function(error){
     console.log("Error occurred while checking if beacon was in range... (Should never happen)");
});

Response example:

{
    "beacons": [
        {
            "uuid": "110E8400-E29B-11D4-A716-446655440000",
            "major": "major_beacon",
            "minor": "minor_beacon",
            "tag": "example_beacon_tag",
            "proximity": 1
        }
    ]
}
  • beacons: array with beacon objects:
    • uuid: string which contains beacon universal unique identifier
    • major: string which contains the major of the beacon
    • minor: string which contains the minor of the beacon
    • tag: string which contains beacon tag
    • proximity: integer which defines the proximity:

      • BEACON_PROXIMITY_UNKNOWN = 0
      • BEACON_PROXIMITY_IMMEDIATE = 1
      • BEACON_PROXIMITY_NEAR = 2
      • BEACON_PROXIMITY_FAR = 3

rogerthat.system

Rogerthat system data has the following format:

{
    "system": {
        "os": "ios",
        "version": "7.1",
        "appVersion": "1.0.150.I"
    }
}

To retrieve Rogerthat system data in your javascript, you can use the following functions:

  • rogerthat.system.os: retrieve the system os, can be:
    • ios
    • android
    • unknown
  • rogerthat.system.version: retrieve system version (“unknown” if the version is not available)
  • rogerthat.system.appVersion: retrieve the version of the Rogerthat application of your system, the result will be “unknown” if the version is previous than the 1.0.150.I for iOS or 1.0.1002.A for Android
  • rogerthat.system.onBackendConnectivityChanged(function(result) {}): start receiving Internet connectivity changes.

Example:

var os = rogerthat.system.os;
var version = rogerthat.system.version;
var appVersion = rogerthat.system.appVersion;

rogerthat.callbacks.onBackendConnectivityChanged(function(isConnected) {
    if (isConnected) {
        console.log('We are now connected to the Internet');
    } else {
        console.log('There is no Internet connectivity');
    }
});

rogerthat.system.onBackendConnectivityChanged(function(result) {
    // From now on, we will receive updates on rogerthat.callbacks.onBackendConnectivityChanged
    if (result.connected) {
        console.log('We are connected to the Internet');
    } else {
        console.log('There is no Internet connectivity');
    }
});

rogerthat.message

Messaging API including a method to open a message thread.

  • rogerthat.message.open(messageKey, function(){}, function(){}): open an existing conversation

Example:

var messageKey = "...";  // The message key. Could be a chat or a flow or any other message key.
var onSuccess = function() {
    console.log("The message is successfully opened by the app"); 
};
var onError = function(error) {
    // error: {"type": "MessageNotFound"}
    console.log("The message is not found");
};

rogerthat.message.open(messageKey, onSuccess, onError);

rogerthat.camera

API methods to start/stop scanning for QR codes.

  • rogerthat.camera.startScanningQrCode(cameraType, onSuccess, onError): open the camera to start scanning for QR codes.
  • rogerthat.camera.stopScanningQrCode(cameraType, onSuccess, onError): close the camera to stop scanning for QR codes.

    • cameraType can be “front” or “back”.

See rogerthat.callbacks for an example.

rogerthat.security

API methods related to security. Only applicable for apps which ask for a security PIN code during the account creation.

  • rogerthat.security.sign(message, payload, forcePin, onSuccess, onError): Sign the hash of the provided payload

    • message: An optional string containing the message which is shown at the moment the user is asked to enter his PIN code.
    • payload: A string containing the date that needs to be signed.
    • forcePin: Normally the user shouldn’t enter his PIN more than once in 5 minutes. Within these 5 minutes the payload is automatically signed. You can overrule this behavior by setting forcePin to true.
    • onSuccess: The method that will be called with the signed payload.
    • onError: The method that will be called when something went wrong.
  • rogerthat.security.verify(payload, signature, onSuccess, onError): Verify a signature for a certain payload.

Example:

var message = 'To confirm this payment please enter your pin code';
var payload = JSON.stringify({amount: 500, fromUser: "geert@mobicage.com", toUser: "bart@mobicage.com"});

var onError = function(error) {
    // error: {"exception": "<The error message>"}
    console.log(error);
};

rogerthat.security.sign(message, payload, true, function(signature) {
    console.log('The payload has been successfully signed.');
    
    rogerthat.security.verify(payload, signature, function(result) {
        // result: {"valid": true}
        if (result.valid) {
            console.log('The signature has been successfully verified.');
        } else {
            console.log('The signature was not valid!');
        }
    }, onError);
}, onError);

rogerthat.features

Check if your system support the system features, you can use the following functions:

  • rogerthat.features.base64URI: check if the user’s device supports loading images via base64 encoded data
  • rogerthat.features.backgroundSize: check if the user’s device supports CSS3
  • rogerthat.features.beacons: check if the user’s device has iBeacon support
  • rogerthat.features.callback: a callback which will be called after the availability of a feature has been verified

The result can take these values:

  • FEATURE_CHECKING = 0
  • FEATURE_SUPPORTED = 1
  • FEATURE_NON_SUPPORTED = 2

Example:

function alertAfterFeaturesChecked (feature) {
    if (feature) {
        var supported =  rogerthat.features[feature] == FEATURE_SUPPORTED;
        console.log("Feature " + feature + " is " + (supported ? "" : "not") + "  supported!");
    }

    if (rogerthat.features.base64URI === FEATURE_CHECKING 
            || rogerthat.features.backgroundSize === FEATURE_CHECKING 
            || rogerthat.features.beacons === FEATURE_CHECKING) {

        // wait until all features are verified
        rogerthat.features.callback = alertAfterFeaturesChecked;
        return;
    }

    alert('All necessary features are verified.')
};

rogerthat.callbacks.ready(function () {
    alertAfterFeaturesChecked();
});

rogerthat.ui

UI related utility methods.

var guid = rogerthat.ui.hideKeyboard();  // Android only. Hide the android keyboard.

rogerthat.util

Utility methods.

  • rogerthat.util.uuid(): Generate a random UUID.
  • rogerthat.util.playAudio(path, callback): Play a sound file which is located in the branding zip.
  • rogerthat.util.isConnectedToInternet(callback): Check the Internet connectivity.
var guid = rogerthat.util.uuid(); // Eg. 1d50c98d-9314-4e5d-8abc-be6373e027e2

rogerthat.util.playAudio('sounds/notification.mp3', function() {
    console.log('You should be able to hear the sound right now');
});

rogerthat.util.isConnectedToInternet(function(result) {
    console.log('Connected to Internet? ' + result.connected);
    console.log('Connected to WiFi? ' + result.connectedToWifi);
});

rogerthat.callbacks

The different callbacks you can receive:

  • rogerthat.callbacks.ready(function(){}): Rogerthat user and service data has been set
  • rogerthat.callbacks.backPressed(function(){}): Rogerthat user pressed back button
  • rogerthat.callbacks.onPause(function(){}): The HTML5 app is not visible anymore
  • rogerthat.callbacks.onResume(function(){}): The HTML5 app is visible again
  • rogerthat.callbacks.userDataUpdated(function(){}): The app received an update and rogerthat.user.data is updated.
  • rogerthat.callbacks.serviceDataUpdated(function(){}): The app received an update and rogerthat.service.data is updated.
  • rogerthat.callbacks.onBackendConnectivityChanged(function(result){}: The device its Internet connectivity has changed.
  • rogerthat.callbacks.onBeaconInReach(function(beacon){}): The app detected a beacon.
  • rogerthat.callbacks.onBeaconOutOfReach(function(beacon){}: The user went out of reach of a beacon.
  • rogerthat.callbacks.qrCodeScanned(function(result){}: A QR code has been scanned as result of rogerthat.camera.startScanningQrCode
rogerthat.callbacks.ready(function(){
    console.log("You received a ready callback");
});

rogerthat.callbacks.backPressed(function(){
    console.log("You received a backPressed callback");
});

rogerthat.callbacks.onPause(function(){
    console.log("You received a Pause callback");
});

rogerthat.callbacks.onResume(function(){
    console.log("You received a Resume callback");
});

rogerthat.callbacks.userDataUpdated(function(){
    console.log("User data updated");
});

rogerthat.callbacks.serviceDataUpdated(function(){
    console.log("Service data updated");
});

// --- Internet ----------------------------

rogerthat.callbacks.onBackendConnectivityChanged(function(isConnected) {
    console.log(isConnected ? 'We are connected to the Internet' : 'There is no Internet connectivity');
});

rogerthat.system.onBackendConnectivityChanged(function(result) {
    // From now on, we will receive updates on rogerthat.callbacks.onBackendConnectivityChanged
    console.log(result.connected ? 'We are connected to the Internet' : 'There is no Internet connectivity');
});

// --- Beacons ----------------------------

rogerthat.callbacks.onBeaconInReach(function(beacon){
    console.log(beacon)
};

rogerthat.callbacks.onBeaconOutOfReach(function(beacon){
    console.log(beacon);
});

// --- Camera ----------------------------

var onCameraError = function(error) {
    // error: {"exception": "<The error message>"}
    console.log("An error occurred,", error);
};
var onCameraStarted = function() {
    console.log("The camera has been opened. We can soon expect the qrCodeScanned callback to be triggered."); 
};
var onCameraStopped = function() {
    console.log("The camera has been closed."); 
};

rogerthat.callbacks.qrCodeScanned(function(result) {
    /*
    This method is called twice. If the smartphone is connected to the Internet,
    the app will request the details of the scanned QR code. 

    Example result for the first invocation:
    {
        "status": "resolving",
        "content": "https://rogerth.at/S/-I44M9SX411"
    }

    Example result for the second invocation:
    {
        "status": "resolved",
        "content": "https://rogerth.at/S/-I44M9SX411",
        "userDetails": {
            "appId": "rogerthat",
            "name": "Bart Testaccount",
            "email": "bart@mobicage.com"
        }
    }

    Example result in case of error:
    {
        "status": "error",
        "content": "<The error message>"
    }
    */
    console.log("The camera detected a QR code.", result);

    rogerthat.camera.stopScanningQrCode("back", onCameraStopped, onCameraError);
});

rogerthat.camera.startScanningQrCode("back", onCameraStarted, onCameraError);

Example response for BeaconInReach or BeaconOutOfReach callbacks:

{
    "beacon": {
        "uuid": "110E8400-E29B-11D4-A716-446655440000",
        "major": "10256",
        "minor": "22001",
        "tag": "example_beacon_tag",
        "proximity": 1
    }
}

rogerthat-api.js, a library that provides reliable communication to the backend

The rogerthat-api.js library creates a reliable path to your backend, also when the user of the HTML5 app is not connected to the internet. The library is pre-packaged with the Rogerthat app, so developers do not need to package it themselves with their app.

In order to use this library, you need to load rogerthat/rogerthat-1.0.js and rogerthat/rogerthat.api-1.0.js

Example:

<script src="rogerthat/rogerthat-1.0.js" type="text/javascript"></script>
<script src="rogerthat/rogerthat.api-1.0.js" type="text/javascript"></script>

rogerthat.api.call

This method will result in triggering the system.api_call service callback, wether the user is online on invocation or not. If the user is not online on invocation, the api call will be executed as soon as the user is connected to the internet again. The result of the system.api_call service callback, is delivered via the resultReceived callback, documented below.

rogerthat.api.call(method,params,tag): call the API

  • method: string with the call method
  • params: JSON string with the call params
  • tag: string with the call tag

Example:

rogerthat.api.call("add_to_calender",{"eventId": "5754903989321728"}, "tag1");

rogerthat.api.callbacks.resultReceived

rogerthat.api.callbacks.resultReceived(function(method,result,error,tag){}): receive the call result

  • method: string with the call method
  • result: JSON string with the result of the call
  • error: string with code error
  • tag: string with the call tag

Example:

rogerthat.api.callbacks.resultReceived(function(method,result,error,tag){
    console.log(method);
    console.log(result);
    console.log(error);
    console.log(tag);
}),

Response:

{
    "method": "add_to_calendar",
    "result": {"success": "true"},
    "error": null,
    "tag": "tag1"
}

jquery

The Rogerthat app comes pre-packaged with jquery and jquery mobile. Using the pre-packaged versions of jquery and jquery mobile will make your HTML5 app significantly smaller which results in faster download and less bandwith usage for the users of your services.

In your javascript, you can use the following contents of the jquery library:

  • jquery-1.11.0.min.js
  • jquery.mobile-1.4.2.min.js
  • jquery.mobile.inline-png-1.4.2.min.css
  • images/ajax-loader.gif

Example:

<script src="jquery/jquery-1.11.0.min.js"></script>
<link rel="stylesheet" href="jquery/jquery.mobile.inline-png-1.4.2.min.css"/>
<script src="jquery/jquery.mobile-1.4.2.min.js"></script>

Troubleshooting an HTML5 app running in a Rogerthat service

You can forward the logs created by console.log in HTML5 apps to your pc.

Therefore you have to login on https://rogerth.at with the same Rogerthat account you registered the Rogerthat app. Then navigate to the “Friends & me” tab and open the “Mobiles” pane. In the “Mobiles” pane navigate to the “Developer” tab and click the “Open log viewer” tab.

open-logs-viewer

This will open the log viewer tab as shown below:
logs-viewer