Developer

If you develop your own Android application you can extend the functionality of movisensXS. To use this functionality please contact movisensXS to get a developer account.

There are several use cases to integrate movisensXS with your app:

1. Your application starts or stops the sampling.
2. Your application triggers something in the sampling (e.g. your app triggers an alarm or a form).
3. Your application is triggered by the movisensXS sampling (e.g. movisensXS tells your application that a form has been completed).
4. Your application provides an item format. movisensXS calls your app during a form. Your app returns its result to movisensXS which will store it.

Start / Stop Sampling

Start the Sampling from your app:

sendBroadcast(new Intent("com.movisens.xs.android.core.intent.action.START_SAMPLING"));

Stop the Sampling from your app:

sendBroadcast(new Intent("com.movisens.xs.android.core.intent.action.STOP_SAMPLING"));

Trigger Sampling

Trigger something in the sampling by sending an broadcast from your app to an *Intent Received *block in the movisensXS sampling (this block has to be added):

String reason = "High Heart Rate: 160bpm"; // Warning: The maximum length of the reason is: 230 characters - (intent action length (e.g. "com.yourApp.YourBroadcastName" = 29))
Intent intent = new Intent("com.yourApp.YourBroadcastName");
intent.putExtra("value", reason);
sendBroadcast(intent);

Receive a notification from movisensXS by receiving a broadcast in your app from an Send Intent block in the movisensXS sampling (this block has to be added):

public String intentName = "com.yourApp.YourReceiverName";
private BroadcastReceiver yourReceiver;
private IntentFilter theFilter;
theFilter = new IntentFilter();
theFilter.addAction(intentName);
this.yourReceiver = new BroadcastReceiver() {
    @Override
    public void onReceive(Context context, Intent intent) {
        //This is executed if the "Send Intent" block in the sampling is reached.
        //Your code goes here
    }
};
registerReceiver(this.yourReceiver, theFilter);

Custom Items

Your application can be started from inside a form. To do so include an External Application item in your form and specify the name of the action that starts your activity (e.g. : "com.yourApp.TEST").

In your application you have to add an intent filter that movisensXS can call your action:

<activity android:name=".YourSpecialTestActivity">
    <intent-filter>
        <action android:name="com.yourApp.TEST" />
        <category android:name="android.intent.category.DEFAULT" />
    </intent-filter>
</activity>

In your developed activity just return your result as a string back to movisensXS with the following code:

String answer = "This is the result of your app";
Intent intent = new Intent();
intent.putExtra("value", answer);
setResult(RESULT_OK, intent);
finish();

Example Project

An example project that integrates all the samples above can be found on GitHub (opens new window).

GIS-Trigger

This Trigger sends the location to an external Server which decides if a trigger should happen. This external server can e.g. use a geographic information system (GIS) to analyzes the data. As interface a HTTP-REST-interface is used. This interface must be accessible via a connection which is encrypted with SSL with a valid certificate. Furthermore the interface has to have a version number, so that if there are major changes there will be no incompatibility with the live system. Communication with the interface works via JSON-format.

When the Smartphone detects that the participant has changed its location, it will send the current location as well as the last location to the GIS-server. The server the decides based on its information if a trigger should be issued.

Request

Parameter	Type	Description
currentLocation	Location	Current location object
lastLocation	Location	Last Location object

Location-Type

Parameter	Type	Description
latitude	Float	Latitude
longitude	Float	Longitude
accuracy	Float	Accuracy of GPS reading, in meters
timestamp	String <ISO8601>	Timestamp of location data collection

Response

Parameter	Type	Description
trigger	Boolean	true if the smartphone should trigger a questionnaire, false if not

Example

Example Request the Smartphone sends to the server

curl -H "Content-type: application/json" -d 'see below' https://server-url.com/api/v1/location/update

{
  "currentLocation": {
    "latitude": 45.5165,
    "longitude": -122.6764,
    "accuracy": 120.0,
    "timestamp": "2014-02-18T15:04:53-0700"
  },
  "lastLocation": {
    "latitude": 45.5165,
    "longitude": -122.6764,
    "accuracy": 10.2,
    "timestamp": "2014-02-18T15:03:53-0700"
  }
}

Example Server Response that triggers

{
  "trigger": true
}