Developer

Extend movisensXS with your own app

Use Cases

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.

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-Typ
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
}