Repackaging AWARE features as cordova plugins

[xubowenhaoren]

Hello,

After a lengthy trial-and-error of integrating emission into AWARE, we find out that it would be more flexible to merge the AWARE sync adapters and sensors to emission directly. What suggestions do you have for us to get started on the migration?

[shankari]

The high level goal is that we want to modify the AWARE code as little as possible so that we can pull updates from them as they occur. This implies that the ideal structure will involve a wrapper that represents the cordova bits.

First, let us consider the anatomy of an AWARE plugin.
@xubowenhaoren pointed to the battery plugin as the easiest to understand.

https://github.com/denzilferreira/aware-client/blob/master/aware-core/src/main/java/com/aware/Battery.java

It looks like:

1. AWARE does not use SQLite directly but uses the ContentProvider interface instead. The rows are constructed as ContentValues objects and then put into the resolver

   context.getContentResolver().insert(Battery_Data.CONTENT_URI, rowData);
   

2. Each ContentProvider (and by extension, each sensor), has its own SyncAdapter associated with it. The sync request is set here ContentResolver.requestSync(request);

So probably the easiest approach is to continue using the ContentProvider architecture for AWARE. In terms of syncing, you can choose to sync to an AWARE server and then merge the data on the server side, or you can write a new SyncAdapter that syncs the data to an e-mission server.

Note that every sensor in AWARE has its own sync adapter. But the base class appears to be
https://github.com/denzilferreira/aware-client/blob/master/aware-core/src/main/java/com/aware/syncadapters/AwareSyncAdapter.java
Modifying the onPerformSync method of that adapter (or any of the methods it calls, such as offloadData) should make it possible to choose where the data goes to the server.

But that decision is independent of pluginizing the sensor. IMHO, the easiest way to pluginize this code is to leave it untouched and to write a wrapper that inherits from CordovaPlugin. You could either define an external method to start the data collection, which would be consistent with accepting consent and then turning on tracking, or you could just implement the init method of the plugin and have it create the BatteryService and start it.

[shankari]

You could also choose to do this in two steps:

1. Only pluginize the sensor, and continue to send the data to an AWARE server
2. After getting that to work, implement a new sync adapter to e-mission if necessary

That will also get you familiar with cordova and reduce the unknown factor.

[shankari]

There are many examples of cordova plugins on the internet. Including the Cordova battery plugin https://github.com/apache/cordova-plugin-battery-status that you can look at for an example of the the cordova plugin interface.

This defines an externally callable method called "start" which sets up the listeners. In your case, that would call onCreate on the AWARE battery service. You would then call start from the javascript during onboarding and everything will Just Work.
https://github.com/apache/cordova-plugin-battery-status/blob/master/src/android/BatteryListener.java#L57

I think cordova also has a user guide or some kind of similar documentation.

[xubowenhaoren]

You mentioned that each e-mission plugin only runs after the user consents. So in the repackaging, do I need to check for user contents as well?

[shankari]

It is up to you. You are building your own version of the app and can do whatever you want. Theoretically, you can call markConsented on the e-mission plugin without showing anything to the user since it is just a javascript call.

So it is possible using the e-mission plugin to skip the consent. I just chose to believe that most people will be careful of consent and gave them the tools to handle it properly. e.g. the markConsented method.

So basically if I didn't have the method, then people would have to build it in and everybody is lazy. I made it easier (the default) to start tracking only after consent, and harder to remove it (have to edit onboarding).

[shankari]

@ariasfelipe also wrote a shake detection plugin that used local processing on the phone to detect shakes. This is a much more scalable solution because otherwise the volume of accelerometer data is too high. He demoed it, but I am not sure how well it works in the real world.
https://github.com/e-mission/e-mission-shake-detect/

[shankari]

@xubowenhaoren if you just want an example of wrapping native code in a plugin, I would not recommend the shake detect code, since it is much more complex than you need.
You should use the step-by-step cordova guide
https://cordova.apache.org/docs/en/latest/guide/hybrid/plugins/
combined with the simplistic example
https://github.com/ModusCreateOrg/cordova-plugin-example
or other tutorials on the internet
https://blogs.sap.com/2017/08/18/step-by-step-to-create-a-custom-cordova-plugin-for-android-and-consume-it-in-your-ui5-application/

The shake detect code does allow the user to configure the prompt that is displayed when the shake is detected. What kind of local processing are you planning to do, and what do you want as the resulting output?

[xubowenhaoren]

I want the output to match current AWARE standards, making a functionally equivalent migration. Therefore, I would likely need to follow AWARE's approach of wrapping data. Here is one of their data providers.

[shankari]

with the approach outlined in #501 (comment) you will continue to use the AWARE data format. In fact, you will continue to use their local storage and their server (at least in step 1). So I am not sure what this comment means.

Note that in #501 (comment), I am talking about wrapping code, not data

Update 1:

You don't care about the AWARE implementation details. Once the AWARE services are launched in the background, they will continue to do their stuff in their way. If that changes in the new rewrite, you are not affected.

All you need to do is to wrap the code and launch the aware services properly from the init or exec function of the plugin. Nothing else.

Update 2:

In other words, remember all the lectures on software modularity :) focus on the interface and not the implementation.

[xubowenhaoren]

Thanks for the clarification. It seems like you've made structural changes to the e-mission-docs and I cannot find your notes on how to add a new plugin to a client. The closest I could find is this deployment guide.

[shankari]

@xubowenhaoren I don't think I ever had notes on how to add a new plugin to a client.

Apache Cordova is standard, well-documented technology, and I don't want to duplicate their documentation.

I have added links to the Apache Cordova documentation on creating and managing plugins
#501 (comment)
along with a link to a third party guide.

[xubowenhaoren]

Now, looking back at what you initially suggested last time and what I've done at this point, I'm afraid that my approach has been somewhat misdirected. What I've done is that I tried to copy over AWARE codes, change them to override e-mission methods and fix any dependency issues along the way. With that said, there are certainly AWARE modules (e.g. SSL certificate helpers) that I don't know how to handle yet.

I think this is NOT what you meant by "creating wrappers" to codes (not data).

[xubowenhaoren]

About the user consent: before we start collectin the user data, we would ask the participant to sign a consent form. This is done before the participants install their apps, and it's very unlikely that the consent criteria need to change during the study. So we don't need to handle consents in this repackaging of the app.

[shankari]

I suggest that you create a cordova plugin with the following interface.

in www/aware.js:

/*global cordova, module*/

var exec = require("cordova/exec")

var Aware = {
}

in src/android/AwarePlugin.java something like this

import aware.....AwareService;

public class AwarePlugin extends CordovaPlugin {
    public static final String TAG = "AwarePlugin";

    @Override
    public void pluginInitialize() {
        AwareService service = new AwareService();
        service.start();
    }
}

[xubowenhaoren]

AWARE clients read aware-core status and modify aware-core settings via a central Aware.settings method. In this repackaging, this would not be directly accessible. Should I then expose Aware.settings in aware.js as JS methods, then use the AwarePlugin.java interface to call the native Aware.settings method?