Navbar
cURL Java ObjC Swift

Introduction

Welcome to the HyperTrack documentation!

You can use our Live and History features through iOS & Android SDKs, a public REST API, webhooks, or data exports.

Please select the documentation you are looking for from the left-side navigation.

API: Live

Live API lets you retrieve the current location and movement status data for your devices. Developers use it in applications to dispatch jobs or assign work to nearest available users.

API requirements

Using Live API requires that you:

Authentication

Basic Auth with AccountId and SecretKey

HTTP Request

GET https://v3.api.hypertrack.com/live/{device-id}

curl -H 'Content-Type: application/json' \
     -u {AccountId}:{SecretKey}
     'https://v3.api.hypertrack.com/live/00112233-4455-6677-8899-AABBCCDDEEFF'

Path Parameters

You can pass a device-id to retrieve a single device. If no device-id is given, all devices associated with the account will be returned.

Name Type Description
device-id string (optional) Unique identifier representing a device

HTTP Response

[{
  "device_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
  "location": {
    "data": {
      "speed": 4.20,
      "altitude": 1.17,
      "location_accuracy": 14.09,
      "location": {
        "type": "Point",
        "coordinates": [
          -122.3980960195712,
          37.7930386903944
        ]
      },
      "bearing": 193.12
    },
    "recorded_at": "2019-05-01T21:07:48.883790Z"
  },
  "activity": {
    "data": {
      "value": "stop"
    },
    "recorded_at": "2019-05-01T21:07:53.883790Z"
  },
  "device_health": {
    "data": {
      "value": "outage.paused",
      "hint": "tracking.paused"
    },
    "recorded_at": "2019-05-03T06:25:51.238000Z"
  },
  "device_status": "inactive",
  "views":{
    "public_href":"https://devpoc-track.htdev.hypertrack.com/abcdef",
    "embed_href":"https://devpoc-embed.htdev.hypertrack.com/devices/00112233-4455-6677-8899-AABBCCDDEEFF?publishable_key=abc"
  },
  "metadata":{
    "key":"12345"
  }
}]
Name Type Description
device_id string Unique device identifier
location object
location.data object
location.data.speed number (optional) speed in m/s
location.data.altitude number (optional) altitude in m
location.data.location_accuracy number (optional) accuracy in m
location.data.location object Location in GeoJSON format
location.data.location.type string As of right now, only Point is supported
location.data.location.coordinates array Array of longitude and latitude
location.bearing number (optional) bearing in degrees
location.recorded_at string ISO 8601 date when the location was recorded
activity object
activity.data object
activity.value string Activity type. Could be one of walk, run, drive, cycle, stop, moving
activity.recorded_at string ISO 8601 date string when the activity was recorded
device_health object (optional) Device health for inactive devices (see device_status)
device_health.data object
device_health.data.value string Outage type. Could be one of outage.denied, outage.disabled, outage.paused, outage.hardware, outage.software, outage.network
device_health.data.hint string (optional) details about the reason for the outage provided by the OS. Subject to change
device_health.recorded_at string ISO 8601 date string when the device health was recorded
device_status string Device status. Can be one of active, inactive and disconnected
views object
views.embed_href string Embed widget URL
views.public_href string Public tracking URL
metadata string Device metadata submitted via Mobile SDKs (Android or iOS)

HTTP Error Codes

Below is a list of the HTTP error codes this endpoint returns.

{
    "status": 404,
    "message": "device id: 00112233-4455-6677-8899-AABBCCDDEEFF not found"
}
HTTP Status Description
401 Unauthorized: No valid credentials provided
403 Forbidden
404 Device ID not found
500 Something went wrong on our side. Please try again later

API: Geofences

Geofences API lets you create and manage geofences for your devices. Developers use it in applications to get notified when their devices arrive at or leave from specific places ("geofences").

API requirements

Using Geofences API requires that you:

Authentication

Basic Auth with AccountId and SecretKey

Create Geofences

POST https://v3.api.hypertrack.com/geofences

curl -H 'Content-Type: application/json' \
     -u {AccountId}:{SecretKey}
     'https://v3.api.hypertrack.com/geofences'

Request body

{
  "device_ids": ["00112233-4455-6677-8899-AABBCCDDEEFF", ...],
  "delete_at": "2019-05-03T06:25:51.238000Z",
  "location": {
    "type": "Point",
    "coordinates": [
      -122.3980960195712,
      37.7930386903944
    ]
  },
  "radius": 30,
  "metadata": "customer_1234"
}

Here's a sample request for creating a circular geofence.

Name Type Description
location object GeoJSON geometry of type Point or Polygon
device_ids string array List of unique identifiers, each representing a device ID (optional)
single_use boolean Delete geofence after it was used by the first device (optional, defaults to true)
delete_at string Timestamp for deletion (optional)
radius number Defines the radius (in metres) of a circular geofence. Must be present if and only if type of location is Point.
metadata String Any metadata you want to assign to this geofence (optional)

Response

{
  "geofence_id": "ab8c3d31-c8b6-49ba-93f9-3483763394db",
  "device_ids": ["00112233-4455-6677-8899-AABBCCDDEEFF", ...],
  "single_use": false,
  "delete_at": "2019-05-03T06:25:51.238000Z",
  "location": {
    "type": "Point",
    "coordinates": [
      -122.3980960195712,
      37.7930386903944
    ]
  },
  "radius": 30,
  "metadata": "customer_1234"
}
Name Type Description
geofence_id string Unique identifier of the newly created geofence

Request body example with polygon geofence

{
  "device_ids": ["00112233-4455-6677-8899-AABBCCDDEEFF"],
  "single_use": false,
  "delete_at": "2019-05-03T06:25:51.238000Z",
  "location": {
    "type": "Polygon",
    "coordinates": [
      [
        [
          77.6325273513794,
          12.9290394555747
        ],
        [
          77.6331335306168,
          12.9290263845272
        ],
        [
          77.6330584287643,
          12.9290812829221
        ],
        [
          77.6325273513794,
          12.9290394555747
        ]
      ]
    ]
  },
  "metadata": "customer_1234"
}

Here's a sample request for creating a polygon geofence. Note that the location object now has the type "Polygon", and the radius field is absent.

Get geofences

GET https://v3.api.hypertrack.com/geofences/{geofence-id}

Path Parameters

You can pass a geofence-id to retrieve a single geofence. If no geofence-id is given, all geofences associated with the account will be returned.

Name Type Description
geofence-id string (optional) Unique identifier representing a geofence

Response - single geofence

{
  "geofence_id": "ab8c3d31-c8b6-49ba-93f9-3483763394db",
  "device_ids": ["00112233-4455-6677-8899-AABBCCDDEEFF", ...],
  "single_use": false,
  "delete_at": "2019-05-03T06:25:51.238000Z",
  "location": {
    "type": "Point",
    "coordinates": [
      -122.3980960195712,
      37.7930386903944
    ]
  },
  "radius": 30,
  "metadata": "customer_1234",
  "devices_inside": ["00112233-4455-6677-8899-AABBCCDDEEFF", ...]
}
Name Type Description
geofence_id string Unique identifier of the geofence
location object GeoJSON geometry of type Point or Polygon
device_ids string array List of unique identifiers, each representing a device ID (optional)
single_use boolean Delete geofence after it was used by the first device (optional, defaults to true)
delete_at string Timestamp for deletion (optional)
radius number Defines the radius (in metres) of a circular geofence. Present if and only if type of location is Point.
metadata String Metadata that you have assigned to this geofence (optional)
devices_inside string array List of unique identifier representing devices that are currently inside this geofence

Response - all geofences

{
  "items": [
    {
      "geofence_id": "ab8c3d31-c8b6-49ba-93f9-3483763394db",
      "device_ids": ["00112233-4455-6677-8899-AABBCCDDEEFF", ...],
      "single_use": false,
      "delete_at": "2019-05-03T06:25:51.238000Z",
      "location": {
        "type": "Point",
        "coordinates": [
          -122.3980960195712,
          37.7930386903944
        ]
      },
      "radius": 30,
      "metadata": "customer_1234"
    }
  ]
}

Name Type Description
items list of objects List of objects, each representing a geofence

HTTP Error Codes

Below is a list of the HTTP error codes this endpoint returns.

{
    "status": 404,
    "message": "Geofence not found"
}
HTTP Status Description
400 Bad request: Invalid input. Check the message for details.
401 Unauthorized: No valid credentials provided
403 Forbidden
404 Geofence ID not found
500 Something went wrong on our side. Please try again later

Webhooks

Webhooks let you subscribe to a real-time stream of location, movement, and geofence status data generated by HyperTrack. Rather than making an API call, HyperTrack can send an HTTPS request to an endpoint that you specify. Events are published for all devices associated with the account.

Webhooks requirements

Using Live Webhooks requires that you:

Activation

Before we will sent POST requests to your server, a one-time activation is required. Please follow the steps outlined below to complete the activation.

Set Webhook URL

First, you need to visit the Setup page on the dashboard and add your Webhook HTTPS URL.

Retrieve subscription request

{
  "Type" : "SubscriptionConfirmation",
  "MessageId" : "",
  "Token" : "",
  "TopicArn" : "arn:aws:sns:us-west-2:012432584802:location_b29fe6c9-27ef-4551-b3ee-8bb3ec000a3b",
  "Message" : "You have chosen to subscribe to the topic arn:aws:sns:us-west-2:012432584802:location_b29fe6c9-27ef-4551-b3ee-8bb3ec000a3b.\nTo confirm the subscription, visit the SubscribeURL included in this message.",
  "SubscribeURL" : "",
  "Timestamp" : "2019-06-11T13:36:08.195Z",
  "SignatureVersion" : "1",
  "Signature" : "",
  "SigningCertURL" : ""
}

Live Webhooks uses AWS SNS service. AWS SNS will send a subscription confirmation message to your Webhook HTTPS URL in JSON format.

Your Webhook HTTPS URL should receive the POST request, which you should parse to retrieve the SubscribeURL value from the subscription confirmation message.

Confirm subscription

<ConfirmSubscriptionResponse xmlns="http://sns.amazonaws.com/doc/2010-03-31/">
  <ConfirmSubscriptionResult>
    <SubscriptionArn>arn:aws:sns:us-west-2:012432584802:location_b29fe6c9-27ef-4551-b3ee-8bb3ec000a3b:a8fa5eb1-5796-47a0-9ec6-9b8706d893b0</SubscriptionArn>
  </ConfirmSubscriptionResult>
  <ResponseMetadata>
    <RequestId>4dec4e40-4ffe-513f-97c7-1b39fe8e2356</RequestId>
  </ResponseMetadata>
</ConfirmSubscriptionResponse>

Next, you can either programatically visit the location specified by the SubscribeURL itself or make it available to you so that you can manually visit the SubscribeURL in your browser.

When you visit the SubscribeURL, you will receive an XML document containing a SubscriptionArn element. It specifies the ARN for your subscription.

You should use the ARN to verify webhook signatures in order ensure the authenticity. Every webhook will include a x-amz-sns-subscription-arn header that should match the SubscriptionArn.

Processing webhooks

Once you have completed the activation, you will see an array of location, health, and activity change events in the POST request body. Activity and health events contain a snapshot of the last device status (location, health, activity). There might be multiple events if they were pushed in short period of time (1 second or less).

POST Body

The overall POST payload has a static structure. The type of the webhook indicates the structure of the data object.

[{
  "id": "510DBB16-02DD-48EA-9AE8-8A0C03283993",
  "recorded_at": "2019-02-27T22:50:24.538000Z",
  "data": { ... },
  "device_id": "ABCDEFG-SASHA-TEST-DEVICE-ID",
  "type": "",
  "device_movement_status": {...}
}]
Name Type Description
id string Unique webhook identifier
device_id string Unique device identifier
recorded_at string ISO 8601 date when the location was recorded. Not used in summary type
type string Type of webhook data. Could be either location, activity, health, summary, or geofence
data object Either location, activity, health, summary, or geofence data, see details below.
device_movement_status object Last known device status. Available in activity and health events.

Location data

[{
  "id": "510DBB16-02DD-48EA-9AE8-8A0C03283993",
  "recorded_at": "2019-02-27T22:50:24.538000Z",
  "data": {
    "altitude": 495.2,
    "bearing": 90.0,
    "location": {
      "coordinates": [-6.2755, 57.6398983],
      "type": "Point"
    },
    "location_accuracy": 14.087,
    "speed": 0.0
  },
  "device_id": "ABCDEFG-SASHA-TEST-DEVICE-ID",
  "type": "location"
}]
Name Type Description
data.speed number (optional) speed in m/s
data.altitude number (optional) altitude in m
data.location_accuracy number (optional) accuracy in m
data.location object Location in GeoJSON format
data.location.type string As of right now, only Point is supported
data.location.coordinates array Array of longitude and latitude
data.bearing number (optional) bearing in degrees

Activity Data

[{
  "id": "510DBB16-02DD-48EA-9AE8-8A0C03283993",
  "recorded_at": "2019-05-03T19:00:02.227000Z",
  "data": {
    "value": "drive"
  },
  "device_id": "704C6AE3-C298-4608-B330-A18ADA20B34F",
  "type": "activity",
  "device_movement_status": {...}
}]
Name Type Description
data.value string Activity type. Could be one of walk, run, drive, cycle, stop, moving

Health Data

[{
  "id": "510DBB16-02DD-48EA-9AE8-8A0C03283993",
   "recorded_at": "2019-05-22T08:24:07.983000Z",
   "data": {
     "value": "outage.software",
     "hint": "sdk.killed"
   },
   "device_id": "236D3473-26CB-4C8A-9DC8-365C6175DAD4",
   "type": "health",
   "device_movement_status": {...}
 }]
Name Type Description
data.value string Health event type. See below.
data.hint string Health hint. Additional information about the health event.
Health event type Description
outage.denied Permissions denied
resumption.granted Permissions allowed
outage.disabled Permissions denied
resumption.enabled Permissions allowed
outage.stopped Tracking stopped programmatically from host application
resumption.started Tracking resumed programmatically from host application
outage.hardware Tracking not possible due hardware (e.g., GPS) issue
resumption.hardware Tracking resumed after hardware (e.g., GPS) issue
outage.software Tracking stopped by outside software (e.g., OS)
resumption.software Tracking resumed after it was stopped by outside software (e.g., OS)
status.update Additional information about device status. See hint field description below for possible values

Summary Data

[{
  "id": "510DBB16-02DD-48EA-9AE8-8A0C03283993",
  "recorded_at": "2019-02-27T22:50:24.538000Z",
  "data": {
    "distance": 0.584,
    "steps": 36,
    "duration": 300,
    "start_datetime": "2019-05-22T04:30:43.137000Z",
    "end_datetime": "2019-05-22T04:35:43.137000Z",
    "segments": [{
      "type": "drive",
      "distance": 0.584,
      "steps": 36,
      "start_datetime": "2019-05-22T04:30:43.137000Z",
      "end_datetime": "2019-05-22T04:34:43.137000Z",
      "polyline": [
        [
          29.00450601873392,
          41.041697338527136
        ],
        [
          29.00139435450409,
          41.04086798406123
        ],
        [
          28.999380736837104,
          41.040288190483196
        ]
      ]
    }]
  },
  "device_id": "ABCDEFG-SASHA-TEST-DEVICE-ID",
  "type": "summary"
}]
Name Type Description
data.distance float Distance of all segments in kilometers
data.steps int Number of steps of all segments
data.duration int Duration of all segments in seconds
data.segments array Array of segments
data.segments.type string Type of segment. Possible values are: run, drive, cycle, stop, moving, outage.denied, outage.software, outage.stopped, outage.hardware, outage.disabled
data.segments.distance float Segment distance in kilometers
data.segments.steps int Steps added during segment
data.segments.start_datetime string ISO 8601 date when segment started
data.segments.end_datetime string ISO 8601 date when segment ended
data.segments.polyline array Array GPS coordinates in historical order

Geofence Data

If you have set up geofences, you will receive geofence events when a device enters or exits a geofence.

[{
  "id": "510DBB16-02DD-48EA-9AE8-8A0C03283993",
  "recorded_at": "2019-02-27T22:50:24.538000Z",
  "data": {
      "value": "entry",
      "geofence_id": "223BCB91-0BDC-44DC-829A-1ADD9CD0CDF0",
      "geofence_metadata": "customer_1234"
  },
  "device_id": "ABCDEFG-SASHA-TEST-DEVICE-ID",
  "type": "geofence"
}]
Name Type Description
data.value string entry when device enters the geofence. exit when device exits the geofence.
data.geofence_id string Unique identifier of the geofence
data.geofence_metadata String Metadata that you have assigned to this geofence (optional)

Device Movement Status object

{
    "activity": {
        "data": {
          "value": "walk",
          "location": {
            "type": "Point",
            "coordinates": [14.97904782716772, 48.12449241971191]
            }
        },
        "recorded_at": "2019-06-10T09:47:55.149000Z"
    },
    "location": {
        "data": {
          "location":
            {
              "type": "Point",
              "coordinates": [14.979332086976958, 48.12436611556148]
            },
            "accuracy": 165,
            "altitude": 249.39663696289062,
            "bearing": 0.0, "speed": 0.0
        },
        "recorded_at": "2019-06-10T09:53:43.558000Z"
    },
    "health": {
        "data": {
          "hint": "battery.discharging",
          "value": "status.update"
        },
        "recorded_at": "2019-06-10T09:00:08.912000Z"
    },
    "last_updated_at": "2019-06-10T09:53:43.558000Z",
    "previous_activity": {
        "data": {
          "value": "stop",
          "location": {
            "type": "Point",
            "coordinates": [14.979366513252522, 48.12438310261298]
          }
        },
        "recorded_at": "2019-06-10T09:12:53.139000Z"
    },
    "device_status": "active"
}

Name Type Description
activity object Activity Data object
health object Health Data object
location object Location Data object
previous_activity object Previous Activity Data object
last_updated_at string ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date when the status was updated
device_status string Device status on of: active, inactive

Data Exports: History

History data exports give you access to all tracked location, movement, custom event, and summary data on AWS S3. Data engineers use this to power upstream applications and data models.

Data Export requirements

Using History Exports requires that you:

File Format

gzipped json line

Schedule

Daily data exports will be available by 06:00 AM UTC.

JSON format

The exported data is in JSON format and contains the individual data points of all your devices. The export JSON object structure is always the same and event_type defines the structure of event_data.

  {
    "event_id": "2D8A5658-7ADC-47A7-A108-09DDD387E088",
    "device_id": "123E4567-E89B-12D3-A456-426655440000",
    "client_creation_time": "2019-04-30T14:25:01Z",
    "server_received_time": "2019-04-30T14:25:04.635880",
    "event_type": "",
    "event_data": ""
  }
name type description
event_id string Unique event identifier (UUID); every event has a unique event_id
device_id string Unique device identifier; every device has a unique device_id
client_creation_time string ISO 8601 date string when event was created on device
server_received_time string ISO 8601 date string when event was processed on HyperTrack’s servers
event_type string Type of the event. Indicates if the row is a location, activity, health, or summary event
event_data string Event data as serialized JSON string (with new lines as \n), structure based on event_type as described below

Location data

  {
      "location_accuracy": 32.00,
      "altitude": 154.00,
      "location": {
          "type": "Point",
          "coordinates": [-122.50365362344037, 37.761003414611174]
      },
      "speed": 1.20,
      "bearing": 217.03
  }
Name Type Description
location object Location in GeoJSON format
location.type string As of right now, only Point is supported
location.coordinates array Array of longitude and latitude
speed number (optional) speed in m/s
altitude number (optional) altitude in m
location_accuracy number (optional) accuracy in m
bearing number (optional) bearing in degrees

Activity data

{
    "value": "stop"
}
Name Type Description
value string Activity type. Could be one of walk, run, drive, cycle, stop, moving

Health data

Device health data showing tracking outages and resumptions. Health data is available for outage events when an outage effects location data.

{
    "value": "outage.stopped",
    "hint": ""
}
Name Type Description
value string Outage type. Could be one of outage.denied, outage.disabled, outage.stopped, outage.hardware, outage.software
hint string (optional) details about the reason for the outage provided by the OS. Subject to change

Custom events

This data contains the individual data points of all your devices.

{
    "event_id":"11112233-4455-6677-8899-aabbccddeeff",
    "device_id":"123E4567-E89B-12D3-A456-426655440000",
    "client_creation_time":"2019-04-17T08:37:18.979Z",
    "server_received_time":"2019-04-17T08:37:20.528118",
    "custom_event_data":"{\"amount\": 1.0, \"item\": \"Foobar\"}","location_event_id":"ac43e815-af20-4e27-9770-794c339151ee",
    "location_data":"{\"altitude\": 815.2000122070312, \"location\": {\"coordinates\": [77.6328431, 12.9289112], \"type\": \"Point\"}, \"location_accuracy\": 27.252, \"bearing\": 0.0, \"speed\": 0.0}",
    "location_client_creation_time":"2019-04-17T08:37:12.827000Z",
    "activity_event_id":"4223bc0b-610f-4aad-af9d-e181e40b5293",
    "activity_data":"{\"value\": \"stop\"}",
    "activity_client_creation_time":"2019-04-17T08:36:53.747000Z",
    "health_event_id":null,
    "health_data":null,
    "health_client_creation_time":null
}
name type description
event_id string Unique event identifier (UUID)
device_id string Unique device identifier
client_creation_time string ISO 8601 date string when event was created on device
server_received_time string ISO 8601 date string when event was processed on HyperTrack’s servers
custom_event_data string Data submitted as part of the custom event
location_event_id string Unique event identifier (UUID) of location event (see movement data)
location_data string Location data (see movement data)
location_client_creation_time string Client timestamp of location event (see movement data)
activity_event_id string Unique event identifier (UUID) of activity event (see movement data)
activity_data string Activity data (see movement data)
activity_client_creation_time string Client timestamp of activity event (see movement data)
health_event_id string Unique event identifier (UUID) of outage event (see movement data)
health_data string Health data (see movement data)
health_client_creation_time string Client timestamp of health event (see movement data)

Summary Data

{
  "distance": 0.584,
  "steps": 36,
  "duration": 300,
  "start_datetime": "2019-05-22T04:30:43.137000Z",
  "end_datetime": "2019-05-22T04:35:43.137000Z",
  "segments": [{
    "type": "drive",
    "distance": 0.584,
    "steps": 36,
    "start_datetime": "2019-05-22T04:30:43.137000Z",
    "end_datetime": "2019-05-22T04:34:43.137000Z",
    "polyline": [
      [
        29.00450601873392,
        41.041697338527136
      ],
      [
        29.00139435450409,
        41.04086798406123
      ],
      [
        28.999380736837104,
        41.040288190483196
      ]
    ]
  }]
}
Name Type Description
distance float Distance of all segments in kilometers
steps int Number of steps of all segments
duration int Duration of all segments in seconds
segments array Array of segments
segments.type string Type of segment. Possible values are: run, drive, cycle, stop, moving, outage.denied, outage.software, outage.stopped, outage.hardware, outage.disabled
segments.distance float Segment distance in kilometers
segments.steps int Steps added during segment
segments.start_datetime string ISO 8601 date when segment started
segments.end_datetime string ISO 8601 date when segment ended
segments.polyline array Array GPS coordinates in historical order

References

Android SDK

This reference shows methods available in the Android SDK. You can also review the generated JavaDoc files.

Initialize (Android)

Initialize the SDK with your activity and publishable key only.

If you don't want SDK to start tracking and/or request data access permissions immediately, you can use one of overloaded initialize variants and set startTracking or stopTracking to control the tracking status.

HyperTrack.initialize(MyActivity.this, 'your-publishable-key-here');
Parameter Type Description
activity Activity Will be used to add permission request fragment (if required) and to access application's Context
publishableKey String Your publishable key from the dashboard

Initialize with handler (Android)

Initialize the SDK with your activity, publishable key, and a handler.

If you don't want SDK to start tracking and/or request data access permissions immediately, you can use one of overloaded initialize variants and then use pair startTracking(boolean, TrackingInitDelegate) stopTracking() to control tracking status.

class myInitDelegate implements TrackingInitDelegate {
    public void onSuccess() {
        // invoked on successful result
    }

    public void onError(TrackingInitError error) {
        // invoked only in case of failure
    }
}

...

HyperTrack.initialize(MyActivity.this, "your-publishable-key-here", myInitDelegate);
Parameter Type Description
activity Activity Will be used to add permission request fragment (if required) and to access application's Context
publishableKey String Your publishable key from the dashboard
trackingInitDelegate TrackingInitDelegate Handler for initialization result

Initialize with handler and config (Android)

Initialize the SDK with your activity, publishable key, custom configuration, and a handler.

// define the handler
class myInitDelegate implements TrackingInitDelegate {
    public void onSuccess() {
        // invoked on successful result
    }

    public void onError(TrackingInitError error) {
        // invoked only in case of failure
    }
}

...

// initialize the SDK without a handler and disable tracking.
HyperTrack.initialize(MyActivity.this, "your-publishable-key-here", false, false, null);

...

// enable tracking later and pass in new handler.
HyperTrack.startTracking(true, myInitDelegate);
Parameter Type Description
activity Activity Will be used to add permission request fragment (if required) and to access application's Context
publishableKey String Your publishable key from the dashboard
shouldStartTracking boolean Start tracking automatically after initialization
shouldRequestPermissionIfMissing boolean Present permission request dialog if permissions are missing
trackingInitDelegate TrackingInitDelegate Handler for initialization result

Start tracking (Android)

Start tracking. Only required if SDK was initialized without tracking or tracking was stopped before.

class myInitDelegate implements TrackingInitDelegate {
    public void onSuccess() {
        // invoked on successful result
    }

    public void onError(TrackingInitError error) {
        // invoked only in case of failure
    }
}

HyperTrack.startTracking(true, myInitDelegate);
Parameter Type Description
shouldRequestPermissionIfMissing boolean Present permission request dialog (if needed)
delegate TrackingInitDelegate Handler for initialization result (optional)

Stop tracking (Android)

Stop tracking.

HyperTrack.stopTracking();

Check tracking status (Android)

Check tracking status.

HyperTrack.isTracking();

Get device ID (Android)

Obtain device UUID. Returns an empty string if SDK was not yet initialized.

String deviceID = HyperTrack.getDeviceId();

Set name and metadata (Android)

Set name and metadata for device tracking data.

// create new metadata map
Map<String,Object> myMetadata = new HashMap<>();

// add external id to metadata
myMetadata.put('external-id', 'your-external-id');

HyperTrack.setNameAndMetadataForDevice('your-custom-device-name', myMetadata);
Parameter Type Description
name String Custom device name (optional)
metaData Map Custom metadata as key-value pair (optional)

Create custom event (Android)

Create a custom event with configurable payload. Please, bear in mind that this will be serialized as JSON.

// create new event map
Map<String,Object> myEvent = new HashMap<>();

// add event details
myEvent.put("item", "Martin D-18");
myEvent.put("previousOwners", Collections.emptyList());
myEvent.put("price", 7.75);

HyperTrack.customEvent(myEvent);
Parameter Type Description
eventData Map Custom event data as key-value pair

Customize notification (Android)

HyperTrack tracking runs as a separate foreground service. When tracking is activated, users will see a persistent notification. By default, it displays the app icon with text {app name} is running. You can customize the notification appearance.

HyperTrack.addNotificationIconsAndTitle(
    R.drawable.ic_small,
    R.drawable.ic_large,
    notificationTitleText,
    notificationBodyText
);
Parameter Type Description
smallIconId int Small icon ID
largeIconId int Large icon ID
title String Title (optional). Set to null to keep the default title
body String Body (optional). Set to null to keep the default body

iOS SDK

This reference shows methods available in the iOS SDK. This reference is split into Swift and Objective C. Please select the appropriate language in the top right panel.

Initialize (iOS)

Initialize the SDK with your publishable key only (Swift only).

If you don't want SDK to start tracking and/or request data access permissions immediately, you can use one of overloaded initialize variants and set startTracking or stopTracking to control the tracking status.

HyperTrack.initialize(
    publishableKey: "<#Paste your Publishable Key here#>")
Parameter Type Description
publishableKey String Your publishable key from the dashboard

Initialize with handler and config (iOS)

Initialize the SDK with your publishable key, custom configuration, and a handler.

// define an error handler
extension AppDelegate: HyperTrackDelegate {
  func hyperTrack(_ hyperTrack: HyperTrack.Type, didEncounterCriticalError criticalError: HyperTrackCriticalError) {
    /// Handle errors here
  }
}

...

// initialize the SDK and disable tracking
HyperTrack.initialize(
    publishableKey: "<#Paste your Publishable Key here#>",
    delegate: self,
    startsTracking: false,
    requestsPermissions: false)

...

// enable tracking later
HyperTrack.startTracking(requestsPermissions: true)
// define an error handler
@interface AppDelegate () <HTSDKDelegate>
@end

@implementation AppDelegate

- (void)hyperTrack:(Class)hyperTrack didEncounterCriticalError:(HTSDKCriticalError *)criticalError {
    /// Handle errors here
}

@end

...

// initialize the SDK and disable tracking
[HTSDK initializeWithPublishableKey:@"<#Paste your Publishable Key here#>"
                           delegate:self
                     startsTracking:false
                requestsPermissions:false];

...

// enable tracking later
[HTSDK startTrackingWithRequestsPermissions:true];
Parameter Type Description
publishableKey String Your publishable key from the dashboard
startsTracking boolean Start tracking automatically after initialization (optional in Swift, true by default)
requestsPermissions boolean Request Location and Motion permissions on your behalf (optional in Swift, true by default)
delegate Handler Error handler for initialization (optional in Swift, nil by default)

The delegate method is called if the SDK encounters a critical error that prevents it from running. This includes:

Start tracking (iOS)

Start tracking. Only required if SDK was initialized without tracking or tracking was stopped before.

HyperTrack.startTracking(requestsPermissions: true)
[HTSDK startTrackingWithRequestsPermissions:true];
Parameter Type Description
requestsPermissions boolean Request Location and Motion permissions on your behalf (optional in Swift, true by default)

Stop tracking (iOS)

Stop tracking.

HyperTrack.stopTracking()
[HTSDK stopTracking];

Check tracking status (iOS)

Check tracking status.

HyperTrack.isTracking
[HTSDK isTracking]

Get device ID (iOS)

Obtain device UUID. Returns an empty string if SDK was not yet initialized.

HyperTrack.deviceID
[HTSDK deviceID]

Set name and metadata (iOS)

Set name and metadata for device tracking data.

HyperTrack.setDevice(name: "Device name", andMetadata: nil) { (error) in
    /// Handle errors here
}
[HTSDK setDeviceWithName:@"Device name"
        andMetadata:nil
        completionHandler:^(HTSDKDeviceNameError * _Nullable error) {
            /// Handle errors here
       }];
Parameter Type Description
name String Custom device name (optional)
metadata Dictionary (String) Custom metadata as string dictionary (optional)
completionHandler Handler Error handler (optional)

Create custom event (iOS)

Create a custom event with configurable payload. Please, bear in mind that this will be converted to JSON from a Dictionary type.

HyperTrack.sendCustomEvent(withMetadata: ["custom keys": "custom values"]) { (error) in
    /// Handle errors here
}
[HTSDK sendCustomEventWithMetadata:@{ @"custom keys": @"custom values" }
        completionHandler:^(HTSDKCustomEventError * _Nullable error) {
            /// Handle errors here
        }];
Parameter Type Description
metadata Dictionary (String) Custom metadata as string dictionary
completionHandler Handler Error handler (optional)

FAQ

We compiled a list of frequently asked technical questions below. If you these do not answer your questions, please send us an email and we will get back to you as soon as possible.

We currently support Android (API version 19+, starting with Android 4.4 Kit Kat) and iOS (version 10+) devices through native SDKs. All devices need to have GPS modules to be supported.

The Quickstart app is completely open sourced with the MIT License. It is there for you to reduce the time it takes to build your own app. We are actively adding more open sourced apps built with HyperTrack that you can fork and re-purpose for your own needs.

We’re planning to release hybrid SDKs to support these apps. Please cast your vote on our feature request board to help us prioritize effectively.

Live location tracking is a background process that uses sensor signals. Therefore, consuming the energy of the phone. However, we are constantly improving the energy efficiency of our SDKs. Current tests show that we drain less than Uber’s rider app kept in the pocket (without screen time). The caveat with most tests like that is that phones, user behaviors, and tracking environments differ significantly.

In tens of MBs per month on the device that is generating; lower single digit MBs per month on the device that is consuming.

Yes, you can configure webhooks to stream all movement, activity, and custom events to your server in real-time.

You can access and query your data up to 30 days into the past. In case you need more, we suggest to collect daily data exports we can provide you through the export feature.