Developers Introduction


Use GpsGate Push APIs to access event-driven data for building your own responsive apps. Push APIs use a combination of HTTP RPC-style methods and server sent event data.

Version

The SSE APIs are currently in version 1. This version will be supported for two months after the next version is released. There are no currently deprecated versions.


Getting started

The following examples are given in JavaScript for integration into a web application. Integrating requires a method of listening to an SSE event source and a method of making HTTP requests. Most modern software languages have libraries that are capable of both.

Maintaining an event source connection to GpsGate involves implementing some basic functionality that is explained further in the Push specifications documentation. The fastest way to get going is to use the PushClient class that you can find on our GitHub page. PushClient depends on an implementation of EventSource being defined. If you’re operating in an environment without that present, then you can use the EventSource polyfill by Yaffle.

The PushClient mini library wraps the native EventSource functionality and implements keep-alive and some easy helpers to subscribe to the streams that you’ll be wanting to watch while you use the SSE APIs.

Listening to a stream

We will use an instance of the PushClient to listen to the events from a specific GpsGate application.

const = basePath = “https://mytracking.server/comGpsGate/sse”;
const applicationId = 4;

const client = new PushClient();

This client is ready to connect to your server and listen to the streams that you are interested in. For our example, lets connect to listen to Dispatch job data.

When we do this, we will get a handler that can be used to unsubscribe later on, so we’ll store it for later use.

client.open();
let unsubHandler = client.subscribe(“Dispatch_Stream”, function(message) {
// your custom code.
});

We can unsubscribe at any time by using

client.unsubscribe(unsubHandler);

Your handler function in the subscribe call will receive all data from the Dispatch_Stream subscription. You can see details of the shape of the returned data in the documentation and act accordingly.

Getting some data

Your listening push client is a bit like a pipe between the server and your client. It doesn’t tell the server what data you’d specifically like, it just gives it a way to send it to you.

Lets carry on our Dispatch example. To get the server to send some data to your event source listener you’ll need to create some type of Dispatch subscription. There are different types detailed in the documentation, but we’ll choose a user subscription. This type of subscription listens to the information that is relevant for a specific Dispatch worker. It is the most common type of subscriber for a client application to have.

For all these operations, we will need a way of making HTTP requests to the server. In this example, we will use the axios library, but feel free to use your favorite HTTP library.

Let’s log into the server and get an authorization token.

const loginResponse = await axios.post(‘https://mytracking.server/comGpsGate/api/v.1/applications/4/tokens’, {
password: "mypassword",
username: "worker1"
});


With this token, we are able to make the request to subscribe.

const sub = await axios.post(‘https://mytracking.server/comGpsGate/rpc/Dispatch/v.1/subscribeToUser’,
  appId: 4,
  requestedSubscriptionId: “exampleUserSub”,
  startTime: “2018-04-25T13:12:39.700Z”,
  endTime: “2018-04-26T13:12:39.700Z”,
  includeUnscheduled: false,
  workerId: 1234
});

The specifics of the request body supplied in this example are explained in the documentation, but essentially we have asked to be sent all job data for a 24 hour time span for user 1234, and to exclude unscheduled job data from being sent.

Dispatch job subscriptions expire after a default timeout of 15 minutes. An unsubscribed event will be sent to your push client and you can re-initiate the subscription. You can also preemptively re-subscribe to the stream at any time and it will renew your subscription to the full duration.