How to Connect your own App or Service with PowUnity

Owned by christoph federwisch (Unlicensed)
Last updated: Apr 18, 2024 by Maximilian Loy
2 min read

Requirements

  • Management user in Traccar (created by PowUnity)

  • FCM Auth Token so the backend is able to send push notifications to custom app via customer's FCM account (created by customer)

User Management

  1. For each of your app users you need to create a separate user in our GPS backend. See the API documentation on how to do this using HTTP POST

  2. Store the newly created user credentials (email + password) in your specific app / backend and use those credentials to connect to the API (created devices, set alarms,…)

Push Messages

In order for our server to send out push messages

  • App registers with FCM and receives a Push Token

    • TODO: add link to documentation

  • App adds new Push Token to token array in user’s attributes in Traccar → User.attributes.fcmTokens<Brand>[], e.g. fcmTokensFancyApp[]

    • TODO: add sample HTTP call

  • Backend now sends push notifications to customer’s apps

  • Unregistered Push Tokens will be automatically cleaned up by Powunity backend → no handling required

NOTE: Request iOS Critical Alert Notifications so your iPhone users will also be alarmed when the phone is in do-not-disturb. See Request a Critical Alert Notifications Entitlement

Guard / Unguard BikeTrax

For arming and disarming the BikeTrax you have to do one simple step.

In the following description uniqueId refers to the ten digit ID on the sticker on the GPS-hardware, e.g. 47101xxxxx

When you call GET https://traccar.powunity.com/api/devices you get an array where each object / device has a distinct "id" (this one changes when you remove the tracker and add the same again).

So we are talking about device.uniqueId not device.id.

Alert type

Alerts can be either triggert by movement (e.g. bike gets carried away) or by leaving a predefined geofence area (e.g. the bike is not allowed to leave a city).

The alert type is determined by the field guardType within the device's attributes.

If no guardType is defined the backend will always fall back to the type movement.

In case guardType is set to geofence the backend will add a circular shaped geofence to the device defined. The circle’s centre is set to the device’s latest known position and the radius defined by the field geofenceRadius (in metres) in the device's attributes.

In order to use geofence as the guardType the field geofenceRadius must also be defined, otherwise the process of guarding the device will fail.

When disarming a device with geofence the geofence will automatically be deleted by the backend.

URLs

Arming

POST to https://admin.powunity.com/api/devices/<uniqueId>/arm

This will arm the device in the backend, arm the GPS-hardware, and create a geofence at the current position in case the device has the guardType in its attributes set to geofence.

Disarming

POST to https://admin.powunity.com/api/devices/<uniqueId>/disarm

This will disarm the device in the backend, disarm the GPS-hardware, and delete the geofence in case the device has the guardType in its attributes set to geofence.

Response

204 after successfully arming/disarming the device.

401 in case of an authentication error.

Headers

No extra headers required.

Authentication and Authorisation

There are two ways of authenticating and authorising at the API.

Once the backend checked that you are authorised to change this specific device everything will be done automatically.

Username and Password

Include the following headers in request:

{ username: 'abc@example.com', password: 'asdasdasd', }
Auth Token

Send the token set as token on the user object as a query parameter, e.g.

https://admin.powunity.com/api/devices/<uniqueId>/disarm?token=ASDFASDFASDFASDF