It is possible to setup push notifications to be alerted as soon as certain events occur. This page explains the format and transport of these push messages, as well as how to use the web service to set up notifications.
When you set up a notification, event data will be "pushed" to you immediately when our server receives the data from your GPS tracker. Depending on the type of target, this will happen via email, HTTP (POST) or SMS (text messaging).
With the exception of a text message, a list of key/value pairs are programmatically sent which indicate the type of event, the GPS tracker that had the event, and other data. The following values are always available:
When the data is sent via HTTP POST, the key/value pairs are sent using the ubiquitous URL encoding (below, [...] would be substituted for real values):
POST /example-event-script HTTP/1.0 Host: example.com Content-Type: application/x-www-form-urlencoded Content-Length: [...] imei=[...]&name=[...]&event_id=[...]&unix_ts=[...]&iso_8601=[...]
The encoding is always UTF-8.
Sending events via email is mostly for humans to read, so the first part of the message (and the subject) of the email is a very short human-readable message using the GPS tracker's name, Zone name, etc. The key/value pair data is appended to the email, however, should it need to be programmatically processed. If there are line breaks in the data (e.g., address data), the second line will begin with a tab (ASCII:0x09) character, as in the example below.
... [human-readable part of email] ... -----BEGIN EVENT DATA----- imei:[...] name:[...] event_id:[...] unix_ts:[...] iso_8601:[...] address:[first line] [second line] latitude:[...] longitude:[...] -----END EVENT DATA-----
Setting up Event Notifications and Zone Notifications can be a confusing affair. Here are a few tips that might help.
The first thing to do is decide, probably via user input, which notifications ought to be edited. You can follow the URLs from various resources to locate just the part of the notifications that you want to edit.
For example, say you have fetched a Tracker data object. One of its properties is event_notifications_url. You can GET that data object to access Event Notifications just for that Tracker.
Assuming you only want to edit which Target gets the notified for this tracker when the Ignition Off event occurs, you can follow the narrow_url link for that event type (find it in event_types list of the data object you just retrieved, as documented under Event Notifications).
What you have when you follow that URL is a list of notifications which only pertain to both the Tracker and the Ignition Off Event. You can then edit the notifications property: add items, remove items, or change some of the properties of the Notification Specification, and PUT the edited data back to the URL you just retrieved.
The scope of your edits always remains true to the URL you used to fetch the items. So if you have limited the scope to the notifications active for a particular Tracker object, everything in notifications is assumed to be for that Tracker when you PUT it back, and the tracker_url property of the Notification Specification is ignored.
Let's say a user wants to edit the Zone Notifications for a particular tracker. The user wants to setup event sending for all Targets and all Zones, on either entry or exit, for that tracker.
Here's a bit of pseudocode indicating how this task might be accomplished:
// create a service object to manage communication service = gink_service("http://mygink.com/rest/v2/", username, password) // find the event_notifications we want to edit gateway = service.get("gateway") trackers = service.get( gateway.trackers_url ) // assume you have some way to pick the tracker you want tracker = find_tracker( trackers ) event_notifications = service.get( tracker.event_notifications_url ) // reset the event_notifications.notifications list event_notifications.notifications = [] // iterate over all available targets & event types // the are also available in the event_notifications object for target in event_notifications.targets: for event_type in event_notifications.event_types: event_notifications.notifications.push({ event_type_url: event_type.event_type_url, target_url: target.target_url }) // PUT the updated object back to the server service.put( tracker.event_notifications_url, event_notifications )