http.md

HTTP Features

JSON Request Templates

The plugin supports customizable JSON request schemas with the following config options:

Option	Type	Default	Description
httpRootProperty	String	location	The root key in the JSON to render records
locationTemplate	String	undefined	Optional template to render location data
geofenceTemplate	String	undefined	Optional template to render geofence data

httpRootProperty

Traditionally, the plugin had a hard-coded "Location Data Schema", where it automatically appended location-data to the location key in the JSON data, eg:

bgGeo.configure({
  url: 'http://my_url',
  params: {
    myParams: {foo: 'bar'}
  }
});

POST /my_url
{
  "location": {  // <-- hardcoded "httpRootProperty"
    "coords": {
        "latitude": 23.23232323,
        "longitude": 37.37373737
    }
  },
  "myParams": {
    "foo": "bar"
  }
}

With httpRootProperty, you can now customize this key:

bgGeo.configure({
  url: 'http://my_url',
  httpRootProperty: 'data',
  params: {
    myParams: {foo: 'bar'}
  }
});

POST /my_url
{
  "data": {  // <-- customizable "httpRootProperty"!
    "coords": {
        "latitude": 23.23232323,
        "longitude": 37.37373737
    }
  },
  "myParams": {
    "foo": "bar"
  }
}

httpRootProperty: "."

If you'd rather POST your data as the root of the JSON, use httpRootProperty: ".":

bgGeo.configure({
  url: 'http://my_url',
  httpRootProperty: '.',
  params: {
    myParams: {foo: 'bar'}
  }
})

POST /my_url
{
  "coords": {  // <-- location data place *as* the root of the JSON
      "latitude": 23.23232323,
      "longitude": 37.37373737
  },
  "myParams": {
    "foo": "bar"
  }
}

locationTemplate & geofenceTemplate

If you wish to provide your own custom HTTP JSON schema, you can configure distinct templates for both location and geofence data. Evaluate variables in your template using Ruby erb-style tags:

<%= variable_name %>

Example:

bgGeo.configure({
  url: 'http://my_url',
  httpRootProperty: 'data',
  params: {
    myParams: {foo: 'bar'}
  },
  locationTemplate: '{ "lat":<%= latitude %>, "lng":<%= longitude %> }',
  extras: {
    "location_extra_foo": "extra location data"
  }
})

POST /my_url
{
  "data": {
    "lat": 45.5192657,
    "lng": -73.6169116,
    "location_extra_foo": "extra location data"
  },
  "myParams": {
    "foo": "bar"
  }
}

Template Tags

Common Tags

The following template tags are common to both locationTemplate and geofenceTemplate:

Tag	Type	Description
latitude	Float
longitude	Float
speed	Float	Meters
heading	Float	Degress
accuracy	Float	Meters
altitude	Float	Meters
altitude_accuracy	Float	Meters
timestamp	String	ISO-8601
uuid	String	Unique ID
event	String	`motionchange
odometer	Float	Meters
activity.type	String	`still
activity.confidence	Integer	0-100%
battery.level	Float	0-100%
battery.is_charging	Boolean	Is device plugged in?

Geofence Tags

The following template tags are specific to geofenceTemplate only:

Tag	Type	Description
geofence.identifier	String	Which geofence?
geofence.action	String	`ENTER

Quoting String Values

You're completely responsible for "quoting" your own String values. The following will generate a JSON parsing error:

bgGeo.configure({
  locationTemplate: '{ "event":<%= event %> }',
});

In the logs, you'll find:

‼️-[TSLocation templateError:template:] locationTemplate error: Invalid value around character 10.
{ "event":<%= event %> }

To fix this, the String tag <%= event %> must be wrapped in "":

bgGeo.configure({
  locationTemplate: '{ "event":"<%= event %>" }',
});

Boolean, Float and Integer Values

Boolean, Float and Integer values do not require quoting:

bgGeo.configure({
  locationTemplate: '{ "is_moving":<%= is_moving %>, "odometer":<%= odometer %> }',
});

Array Templates

You're not forced to define your templates as an {Object} — You can define them as an [Array] too.

bgGeo.configure({
  url: 'http://my_url',
  httpRootProperty: 'data',
  params: {
    myParams: {foo: 'bar'}
  },
  locationTemplate: '[ <%= latitude %>, <%= longitude %> ]',
  extras: {
    "location_extra_foo": "extra location data"
  }
})

POST /my_url
{
  "data": [
    45.5192657,
    -73.6169116,
    {"location_extra_foo": "extra location data"}  // <-- appended #extras
  ],
  "myParams": {
    "foo": "bar"
  }
}

❗ #extras are automatically appened to the last element of the array as an {Object}.

Array Template with httpRootProperty: "."

⚠️ This case is tricky and should probably be avoided, particularly if you have configured #params, since there no place in the request JSON to append them.

bgGeo.configure({
  url: 'http://my_url',
  httpRootProperty: '.',
  params: {
    myParams: {foo: 'bar'}
  },
  locationTemplate: '[<%=latitude%>, <%=longitude%>]',
  extras: {
    "location_extra_foo": "extra location data"
  }
})

- POST /my_url
 [  // <-- #params are lost.  There's no place in the data-structure to append them.
  45.5192657,
  -73.6169116,
  {
    "location_extra_foo": "extra location data"
  }
]