Skip to content

Latest commit

 

History

History
263 lines (216 loc) · 5.77 KB

http.md

File metadata and controls

263 lines (216 loc) · 5.77 KB
Raw

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"
  }
]