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.

An 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 type="text/javascript" src="jquery/jquery-1.11.0.min.js"></script>
<script type="text/javascript" src="rogerthat/rogerthat-1.0.js"></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.news

  • rogerthat.news.count(onSuccess, onError, params): open the camera to start scanning for QR codes.
    params:

    • service (optional): email of the service you want to count news items for

    onSuccess result:

    • {“count”: 123}
  • rogerthat.news.get(onSuccess, onError, params): get the details of a news item.
    params:

    • news_id id of the news item

    onSuccess result:

    • NewsItem
  • rogerthat.news.list(onSuccess, onError, params): list news items for all or 1 service.
    params:

    • service (optional): email of the service you want to list news items for
    • cursor (optional)
    • limit (optional, default = 10): amount of news items that will be returned

    onSuccess result:

    • {“cursor”: “the cursor string”, “items”: [NewsItem]}
  • NewsItem: For the properties of a newsitem see the result of news.publish

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.
  • rogerthat.util.open(item, onSuccess, onError): Jump to a functionality of the app.

    • item: Object describing which functionality must be opened. It has the following properties:

      • action_type (string): Can be null, “click”, or “cordova”.

        • null: Opens a standard Rogerthat functionality defined by the action property.
        • “click”: A shortcut to a service menu item. Use the action and optionally the service properties to define the menu item referenced by this shortcut.
        • “action”: Searches for services that have a menu item with the tag that is defined by the action property.
        • “cordova”: Opens an embedded cordova application that is built-in at app compilation time. Eg. “rogerthat-payment” in case the app has the Wallet functionality, which was created using cordova.
      • action (string):

        • In case action_type is null: Defines the standard Rogerthat functionality that needs to be opened.

          • “news”: News stream
          • “messages”: Message inbox
          • “friends”: Friend list
          • “services”: Service list
          • “community_services”: Services of type “community service”
          • “merchants”: Services of type “merchant”
          • “associations”: Services of type “association”
          • “emergency_services”: Services of type “care”
          • “scan”: QR code scanner
          • “profile”: User profile
          • “settings”: Settings
          • “profile”: User profile
          • “qrcode”: Loyalty card
          • “directory”: User directory

            • Used in (enterprise) apps that don’t have the friend list. Shows all app users.
          • “more”: More.

            • Used in apps with a 2×3 or 3×3. Shows functionality that is not available the home screen. Can show Friends, Profile, Scan, Settings and/or Stream if not visible on the home screen.
        • In case action_type is “click”:
          The action defines the tag of the service menu item that needs to be opened.
          Use the service property (see below) to define which service the menu item belongs to.
          If not set, then the app’s main service is used.
        • In case action_type is “action”: The tag of a menu item that is searched for.
        • In case action_type is “cordova”: The identifier of the embedded cordova application.
      • collapse (boolean): Only in case the action opens a service list (“services”, “community_services”, “merchants”, “associations” or “emergency_services”).
        If collapse is true and the service list only contains 1 service, then the list will not be shown. The service home screen will be shown instead.
      • service (string): Only in case action is “click”. Defines the service which the referenced menu item belong to. If not set, the app’s main service will be used.
      • title (string): Will be used as title in the navigation bar. Not required when action_type is null.
    • onSuccess: The method that will be called when the functionality is successfully opened.
    • onError: The method that will be called when something went wrong.
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);
});

function openedSuccessfully() {
    console.log('The app functionality is successfully opened.');
}

function failedToOpen(error) {
    console.log('Oh no! An error occurred.', error); // error has a code and a message property.
}

// Open standard Rogerthat functionality (eg. news stream)
rogerthat.util.open({
    action_type: null,
    action: "news"
}, openedSuccessfully, failedToOpen);

// Open another standard Rogerthat functionality (eg. community services, with collapsing)
rogerthat.util.open({
    action_type: null,
    action: "community_services",
    collapse: true
}, openedSuccessfully, failedToOpen);

// Open a shortcut (eg. the menu item of the main service with tag "agenda")
rogerthat.util.open({
    action_type: "click",
    action: "agenda",
    title: "Agenda"
}, openedSuccessfully, failedToOpen);

// Open search by action (eg. all services with a menu item with tag "reserve1")
rogerthat.util.open({
    action_type: "action",
    action: "reserve1",
    title: "Reserve"
}, openedSuccessfully, failedToOpen);

// Open embedded cordova application (eg. the Wallet functionality)
rogerthat.util.open({
    action_type: "cordova",
    action: "rogerthat-payment",
    title: "Wallet"
}, openedSuccessfully, failedToOpen);

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.newsReceived(function(ids){}: The app received a new news item or has received the full news item
  • rogerthat.callbacks.badgeUpdated(function(result){}: The count of unread news/messages/… has changed
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);

// --- News ----------------------------

rogerthat.callbacks.newsReceived(function(ids){
  // array of news ids
});

// --- Badge ----------------------------

rogerthat.callbacks.badgeUpdated(function(result){
  // result.key
  // result.count
});

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 type="text/javascript" src="jquery/jquery.mobile-1.4.2.min.js"></script>
<script type="text/javascript" src="rogerthat/rogerthat-1.0.js"></script>
<script type="text/javascript" src="rogerthat/rogerthat.api-1.0.js"></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