locationTemplate property

String? locationTemplate
getter/setter pair

Optional custom template for rendering location JSON request data in HTTP requests.

The locationTemplate will be evaluated for variables using Ruby erb-style tags:

<%= variable_name %>

See also:

BackgroundGeolocation.ready(Config(
  locationTemplate: '{"lat":<%= latitude %>,"lng":<%= longitude %>,"event":"<%= event %>",isMoving:<%= isMoving %>}'
));

// Or use a compact [Array] template!
BackgroundGeolocation.ready(Config(
  locationTemplate: '[<%=latitude%>, <%=longitude%>, "<%=event%>", <%=is_moving%>]'
))

Warning: quoting String data.

The plugin does not automatically apply double-quotes around String data. The plugin will attempt to JSON encode your template exactly as you're configured.

The following will generate an error:

BackgroundGeolocation.ready(Config(
  locationTemplate: '{"timestamp": <%= timestamp %>}'
));

Since the template-tag timestamp renders a string, the rendered String will look like this:

{"timestamp": 2018-01-01T12:01:01.123Z}

The correct locationTemplate is:

BackgroundGeolocation.ready(Config(
  locationTemplate: '{"timestamp": "<%= timestamp %>"}'
));

{"timestamp": "2018-01-01T12:01:01.123Z"}

Configured extras:

If you've configured extras, these key-value pairs will be merged directly onto your location data. For example:

BackgroundGeolocation.ready(Config(
  httpRootProperty: 'data',
  locationTemplate: '{"lat":<%= latitude %>,"lng":<%= longitude %>}',
  extras: {
    "foo": "bar"
  }
))

Will result in JSON:

{
    "data": {
        "lat":23.23232323,
        "lng":37.37373737,
        "foo":"bar"
    }
}

Template Tags

Tag Type Description
latitude Float
longitude Float
speed Float Meters
heading Float Degrees
accuracy Float Meters
altitude Float Meters
altitude_accuracy Float Meters
timestamp String ISO-8601
uuid String Unique ID
event String motionchange,geofence,heartbeat,providerchange
odometer Float Meters
activity.type String still,on_foot,running,on_bicycle,in_vehicle,unknown
activity.confidence Integer 0-100%
battery.level Float 0-100%
battery.is_charging Boolean Is device plugged in?
mock Boolean true when location was recorded from a Mock location app.
is_moving Boolean true when location was recorded while SDK was in moving state.
timestampMeta Object Renders timestamp meta-data. See Config.enableTimestampMeta.

Implementation

String? locationTemplate;