Hello

This is a Condo Miniapps playground for Android, it is still under development, but already allows you to feel the real process of interaction with the application.

You can find the cordova app itself in the MainCordovaApplication folder, where in the www folder there is an example of interaction with the native api and you can develop something of your own.

Content

1. Getting started
2. Common methods.
3. Navigation system.
4. Supported plugins.
   • iBeacon
5. Working with user input.
6. Environment.
7. Important differences.
8. Testing.
   • 8.1 Testing in Demo environment
   • 8.2 Testing in Production environment
9. Publishing.

1. Getting started

1. Installing the necessary dependencies:

• make sure you have the latest version of Android Studio installed

• install node and npm

  • method 1:

    • install nvm

    • and next launch in terminal:

      nvm install node
      

  • method 2 (for windows): just install node

• cordova installation:

    npm install -g cordova
  

• open Android Studio, choose project folder to open, then open sdk manager

• project is running under android 12 (api level 32), install required dependenies

2. Editing the application

• open the project directory and go to the /MainCordovaApplication/www subdirectory

  it will contain your application code, edit it freely

3. Launching and testing the application

• ⚠️Android app works with miniapps builds for the iOS environment from MainCordovaApplication/platforms/ios.

• For linux and macOS: there is updateCordovaProjectToDemo subtask which runs during project build (file app/build.gradle, 66 line), this subtask automatically builds final cordova app file www.zip (MainCordovaApplication/platforms/ios/www.zip) and copies it into app/src/main/res/raw/www.zip to use it by android app.

• For Windows: before each app build run these scripts:

    cd MainCordovaApplication
    cordova prepare ios
    tar -a -c -f www.zip www
    copy /y  www.zip ..\app\src\main\res\raw\www.zip
  

• open project folder with Android Studio, wait until indexing is complete, then choose real or virtual device and click play button

• if you have this error

accept license agreements by:

    cd ~/Library/Android/sdk/tools/bin/
    ./sdkmanager --licenses

2. Common methods

• authorization

function requestServerAuthorizationByUrl(miniapp_server_init_auth_url, custom_params_reserver_for_future_use, success, error)

example:

        cordova.plugins.condo.requestServerAuthorizationByUrl('https://miniapp.d.doma.ai/oidc/auth', {}, function(response) {
            console.log('recive authorication result => ', JSON.stringify(response));
            window.location.reload();
        }, function(error) {
            console.log(error);
        });

• obtaining a current resident/address

function getCurrentResident(success, error)

example:

        cordova.plugins.condo.getCurrentResident(function(response) {
            console.log("current resident\address => ", JSON.stringify(response));
        }, function(error) {
            console.log(error);
        });

• application closing

function closeApplication(success, error)

example:

        cordova.plugins.condo.closeApplication(function(response) {}, function(error) {});

3. Navigation system.

We provide native navigation for your minapps with js code side control. Each miniapp launches with a system navigation bar and a close button on it. In general, you can implement everything else on your side, make an additional panel or controls for nested navigation and work with them.

But we strongly recommend to do otherwise. You can control what the system navigation bar shows on your side. This is achieved by using the following methods on history object inside condo plugin:

• Add a new item to the navigation stack:

  function pushState(state, title)

  example:

  cordova.plugins.condo.history.pushState({"StateKey": "StateValue"}, "Title for navigation bar");
  

• Replace the current item in the navigation stack:

  function replaceState(state, title)

  example:

  cordova.plugins.condo.history.replaceState({"StateKey": "StateValue"}, "Title for navigation bar");
  

• Take a step back:

  function back()

  example:

  cordova.plugins.condo.history.back();
  

• Take a few steps back:

  function go(amount)

  example:

  cordova.plugins.condo.history.go(-1);

  Note that unlike the system history object, the parameter passed here is always negative and can only lead backwards. We have no possibility to go forward to the place we came back from.

Note: you can make the titles on your side big and beautiful and always pass the title blank to the methods above.

In addition, you need to recognize when a user has pressed the system back button. This is achieved by subscribing to the already existing Cordova backbutton event https://cordova.apache.org/docs/en/12.x/cordova/events/events.html#backbutton This event is called for the system button as well.

document.addEventListener("backbutton", onBackKeyDown, false);

function onBackKeyDown() {
    // Handle the back button
}

And of course after all these changes you can get the State that is now showing on the navigation bar. This is done similarly to the standard system method - by subscribing to the condoPopstate event:

addEventListener("condoPopstate", (event) => {console.log("condoPopstate => ", JSON.stringify(event.state));});

4. Supported plugins

Using Cordova, you can add various plugins to your project. But if the plugin accesses the native part, then this plugin must be supported by our application. Here is a list of such plugins:

1. BLE Peripheral
2. BLE Central
3. iBeacon
4. Camera
5. Network Information
6. Device

4.1. BLE Peripheral

Recommendation to install:

cordova plugin add https://github.com/IRazma/cordova-plugin-ble-peripheral

Difference API:

This plugin support all the functionality specified in the original plugin repository. Our solution has added several methods that are needed to use all the features that miniapps provide:

---

[!Remember]

That the services that you advertise continue to be advertised even when >the application is closed

---

• getBluetoothSystemState();

  Method return JSON object that contains an array of services that are advertised at this moment.

  Example:

  {
      "services": [
          {
              "uuid": "...",
              "isPrimary": true,
              "characteristics": [
                  {
                      "uuid": "...",
                      "properties": 1, // int
                      "permissions": 1 // int
                  },
                  {
                      "uuid": "...",
                      "properties": 3, // int
                      "permissions": 5 // int
                  }
              ]
          }, {...}, ...
      ]
  }

• startSendingStashedReadWriteEvents();

  ⚠️ You should call this method when your miniapp is ready to accept such (read & write) events. Otherwise, you may not receive the read/write requests that were requested when the application was closed (in the background).

4.2. BLE Central

4.3. iBeacon

Recommendation to install:

cordova plugin add https://github.com/IRazma/cordova-plugin-ibeacon

⚠️ Required permissions: beacon

For work with these plugin native_config.json file in your miniapp need to contains beacon permission (mobile_permission)

Difference API:

• Method startRangingBeaconsInRegion(...);

  By default takes 1 parameter: BeaconRegion

  Usage:

  let region = new cordova.plugins.locationManager.BeaconRegion(...)
  cordova.plugins.locationManager.startRangingBeaconsInRegion(region)
      .then(...)
      .fail(...)

  In out project these method can takes second parameter: distance. This distance is needed to determine at what point to send a request to launch the miniapp from the background.

  Usage:

  let region = new cordova.plugins.locationManager.BeaconRegion(...)
  let min_distance = 0.5
  // The miniapp will be launched from the background if the distance to the region is 0.5 meters
  cordova.plugins.locationManager.startRangingBeaconsInRegion(region, min_distance)
      .then(...)
      .fail(...)

5. Working with user input.

Sharing files.

Original Documentation: WEB File API

Example for sharing local document:

    <script>
        function shareSomeDocument() {
            fetch('images.com/some_image.png')
                .then(function(response) {
                    return response.blob()
                })
                .then(function(blob) {
                    var file = new File([blob], "image.png", {type: blob.type});
                    var filesArray = [file];
                        navigator.share({
                        files: filesArray
                    });
                });
            }
    </script>

Caution

On iOS calls to navigator.share with files argument must be called in responce to user interaction (button tap, or alike). Otherwise it throws an error

3.2 Importing Files.

Original Documentation: Using files from web applications

Importing images and video:

Button opens image picker (select one image):

<input type="file" accept="image/*">

Button opens image picker (select multiple images):

<input type="file" accept="image/*" multiple>

Button opens video picker (select one video):

<input type="file" accept="image/*">

Button opens video picker (select multiple videos):

<input type="file" accept="image/*" multiple>

Caution

In miniapps on android, input tags don't support getting a file from the camera.

By default, these inputs run the file selector from the device. To get image/video from the camera, a corresponding plugin was added to our project: cordova-plugin-media-capture

To get image/video from camera use:

// get image from camera
navigator.device.capture.captureImage(...)

// get video from camera
navigator.device.capture.captureImage(...)

Example:

// override default onclick listener
input_element_image.onclick = onClickInput
input_element_video.onclick = onClickVideoInput

function onClickInput(input_element) {
    navigator.device.capture.captureImage(
        (files) => { captureSuccess(files, input_element) }, captureError, { limit : 1 }
    );
    return false
}

function onClickVideoInput(input_element) {
    navigator.device.capture.captureVideo(
        (files) => { captureSuccess(files, input_element) }, captureError, { limit : 1 }
    );
    return false
}

// capture error callback
function captureError(error) {
    console.log('Error code: ' + error.code);
};

// capture success callback
function captureSuccess(mediaFiles, inputElement) {
    var i, path, len;
    for (i = 0, len = mediaFiles.length; i < len; i += 1) {
        console.log(mediaFiles[i])
        path = mediaFiles[i].fullPath;

        var xhr = new XMLHttpRequest()
        xhr.open('GET', path)
        var index = i
        xhr.onload = function (r) {
            var content = xhr.response;
            var blob = new Blob([content]);
            file = new File([blob], mediaFiles[index].name, { type: mediaFiles[index].type })

            var dt  = new DataTransfer();
            dt.items.add(file);
            var file_list = dt.files;

            // insert files to input element
            inputElement.target.files = file_list
        }
        xhr.responseType = 'blob'
        xhr.send()
    }
};

6. Environment.

The plugin provides a hostApplication object that can synchronously output information about the current environment in which the mini-app is running.

• Find out whether the application is looking at the production server or not:

  function isDemoEnvironment()

  example:

  console.log(cordova.plugins.condo.hostApplication.isDemoEnvironment());
  

• The base address of the current server:

  function baseURL()

  example:

  console.log(cordova.plugins.condo.hostApplication.baseURL());
  

• Main application installation ID:

  function installationID()

  example:

  console.log(cordova.plugins.condo.hostApplication.installationID());
  

• Device ID:

  function deviceID()

  example:

  console.log(cordova.plugins.condo.hostApplication.deviceID());
  

• Application locale:

  function locale()

  example:

  console.log(cordova.plugins.condo.hostApplication.locale());
  

7. Important differences.

Unlike the standard Cordova, our application uses an additional configuration file, which must be located in the www directory and named native_config.json

This file is a json file and may contain the following fields:

1. presentationStyle - application display type, required, should be set to present_fullscreen
2. mobile_permissions - An array of strings describing the necessary permissions for the application to work. the array can contain the following values: record_audio, camera, audio_settings, beacon

8. Testing

Demo environment

1. Open Chrome and enter into url field chrome://inspect/#devices Choose WebView in ai.doma.miniappdemo and click "inspect"

   

2. Yay! Standard Chrome debugging tools are connected to your mini-application

   

Production environment

1. Take www.zip archive built for ios environment:

    MainCordovaApplication/platforms/ios/www.zip
   

   If it doesn't exist create it from folder:

    /MainCordovaApplication/platforms/ios/www
   

2. Install Doma app from Google Play

3. The app you downloaded has built-in functionality for debugging mini-applications. To turn it on & off, you can use these deeplinks from your phone:

• Click here to switch on
• Click here to switch off

5. Now, on the main application screen in the list of mini-applications, the last button allows you to download or replace a previously downloaded mini-application from files. When you click on it, you need to select the previously taken www.zip archive.

6. The application loaded in this way has a built-in js console, which is accessible by clicking on the button at the bottom right of the open mini-application and is able to show a lot of additional information, including various errors.

9. Publishing

To publish the mini-application, send the www.zip archive you received during the testing phase to the people at Doma with whom you interact.