Capture GPS Locations

GPS locations can be captured in the foreground (i.e. the user can see that the location is being captured), in the background using the capture-coordinates component or recorded over time as a track.

To use the capture-coordinates component, you need to define a field or variable with type location.

To record GPS tracks you need to define a field with type track.

Capture a single GPS location

To capture a single GPS location in the foreground or background, please refer to the documentation on capture-coordinates:

capture-coordinates

Accessing GPS Information from JavaScript/TypeScript or Format Strings

These properties of a GPS location variable or field can be accessed from JavaScript/TypeScript and Format Strings, but cannot be modified:

• latitude

• longitude

• altitude

• horizontal_accuracy

• vertical_accuracy

• timestamp

Limitation

Capturing the altitude and/or vertical_accuracy is not supported on several platforms / devices, including Android devices. These devices will return null for these fields.

Example — Accessing GPS Information from JavaScript

function update_coordinates() {
    if (view.current_location == null) {
        dialog("Location", "Unknown");
    } else {
        dialog("Location", "" + view.current_location.latitude + ", " + view.current_location.longitude);
    }
}

Example — Accessing GPS Information from Format Strings

<table>
    <info label="Latitude" bind="current_location.latitude" />
    <info label="Longitude" bind="current_location.longitude" />
    <info label="Horizontal Accuracy" bind="current_location.horizontal_accuracy" />
</table>

Recording GPS Tracks

Version compatibility

The GPS tracking feature was introduced in version 4.6 of the JourneyApps Container for Android and iOS.

A custom branded container is necessary for this feature. Please contact JourneyApps Support to request one.

GPS tracks are recorded to a data model field of type track.

The Track.start({'highFrequency': true}) method will start a track in high-frequency update mode (maximum update rate of 10 seconds) and return the track ID which should be saved to a field of type track. Calling Track.start({'highFrequency': false}) will record in low-frequency update mode (maximum update rate of 1 minute).

The Track.stop() method will stop the track recording.

The Track.isTracking() method will return a boolean, indicating if a track is in progress.

Common background tracking issues

Background tracking may not work in the following cases:

• The correct permissions to track location in the background have been disabled.

• If the app is "force-closed" or the OS has closed the app in the background. I.e. the app is no longer running in the background.

• The device has a form of battery saver mode enabled.

A note on the location update rate

The OS of the device determines how often locations GPS location updates are sent to JourneyApps.

If the device's location has not changed, it might not report a new location. This is why the interval between locations on a track often varies and is not exactly 10 seconds or 1 minute.

Example — Recording GPS Tracks

The following example shows how to start and stop GPS track recording.

Data model XML:

schema.xml

<model name="session" label="Session">
    <field name="track_session" label="GPS Track" type="track"/>
    <field name="start_time" label="Start Time" type="datetime"/> <!-- informational -->
    <field name="high_frequency" label="High Frequency" type="boolean" /> <!-- informational -->
    <display>{start_time}</display>
</model>

View XML:

main.view.xml

<view title="Track">
    <var name="session" type="session"/>
    
    <button label="Start Tracking" on-press="startTracking()"/>
    <button label="Stop Tracking" on-press="stopTracking"/>
    <button label="Is Tracking?" on-press="isTracking"/>
    
    <button label="Close" validate="false" on-press="dismiss()"/>
</view>

View JavaScript:

function startTracking() {
  var highFrequency = true; // set to false for low frequency tracking
  var t0 = new Date();
  view.session = DB.session.create({
      start_time: t0,  // informational
      high_frequency: highFrequency // informational
  });
  var opts = {
      'highFrequency': highFrequency
  };
  var trackId = Track.start(opts);
  view.session.track_session = trackId;
  view.session.save()
}

function stopTracking() {
    if (!Track.stop()) {
        dialog('error','unable to stop tracking');
    }
}

function isTracking() {
    var t = Track.isTracking();
    if (t === true) {
        dialog('tracking? yes');
    } else if t === false) {
        dialog('tracking? no');
    } else {
        dialog('','unknown');
    }
}