MTS SDK

30min
Introduction
﻿MTS ﻿The Movement Tracking System (MTS) SDK is an Android SDK written in Java and Kotlin that enables real-time tracking of users and vehicles. It supports integration with both native Android and React Native applications, providing a reliable solution for monitoring movement and managing geofencing events.
The SDK includes a set of APIs that facilitate seamless communication with OS1 backend services, allowing developers to efficiently track movement, listen for event updates, and manage location-based triggers.
Features
Real-time Tracking – Capture and transmit live location updates.
Event Listener Support – Subscribe to movement events and trip status updates.
Geofencing – Define virtual boundaries and receive entry/exit notifications.
Flexible Integration – Supports both native Android and React Native applications.
Sync Location Trace both through REST API & MQTT (MQ Telemetry Transport) Protocol.
The MTS SDK is designed for applications that require accurate movement tracking, geofencing capabilities, and event-driven monitoring.
Currently, supports 21=<SDK<=29.
Prerequisites
Android application written in Java or Kotlin
Minimum Android API level 21 (Lollipop)
Internet access for API communication
OS1 backend services configured and accessible
Supported Versions
Minimum SDK: 24
Maximum SDK: 34
Step 1: Installation
To install MTS SDK, run the following command:
Text
npm install @os1-platform/mts-mobile
npm install @os1-platform/mts-mobile
﻿
Step 2: Import MTS SDK
Import MTS SDK in your project:
JS
import * as MtsLib from '@delhivery/platform-coreos-mts-sdk';
// Add token expiry sync task in root index file (index.ts)
import * as MtsLib from '@delhivery/platform-coreos-mts-sdk';
// Add token expiry sync task in root index file (index.ts)
﻿
2. Register the token expiry sync task in the root index file (index.ts):
JS
import { registerSyncTask } from '@delhivery/platform-coreos-mts-sdk';
registerSyncTask();
import { registerSyncTask } from '@delhivery/platform-coreos-mts-sdk';
registerSyncTask();
﻿
Step 3: Modify MTS Default Configuration
The MTS SDK provides default configuration values that can be modified based on your specific use case. While modifying these values is optional, it allows you to fine-tune parameters such as location update frequency, accuracy, and data transmission behavior to better align with your application's needs.
Below is the default configuration provided by the SDK:
JS
export class MTSDefaults {
  locationFrequency: number = 10000; // in milli seconds (no. of seconds after which location updates will happen)
  distanceAccuracyLimit: number = 250; // in metres
  speedLimit: number = 28; // in m/s
  mode: MTSMode = MTSMode.HYBRID;
  environment: MTSEnv = MTSEnv.DEV;
  batchSize: number = 25;
  isMqttCleanSession: boolean = true;
  mqttKeepAliveInterval: number = 15 * 60; //in seconds
  maxLocationAge: number = 15000; // in milliseconds
  maxTraceSession: number = 24 * 3600 * 100; //in milliseconds
  isOdometerEnabled: boolean = true;
  retriesBeforeFallback: number = 1;
  httpFailureLimit: number = 5;
  dataSendDelay: number = 30000; // in milli seconds
  alarmTime: number = 60000; // in milli seconds
  missingSeqCheckDuration: number = 5 * 60 * 1000; // in milli seconds
  odometerPushFrequency: number = 5 * 60 * 1000; // in milli seconds
  qosLevel: number = 1; // values can be 0 ,1
}
export class MTSDefaults {
  locationFrequency: number = 10000; // in milli seconds (no. of seconds after which location updates will happen)
  distanceAccuracyLimit: number = 250; // in metres
  speedLimit: number = 28; // in m/s
  mode: MTSMode = MTSMode.HYBRID;
  environment: MTSEnv = MTSEnv.DEV;
  batchSize: number = 25;
  isMqttCleanSession: boolean = true;
  mqttKeepAliveInterval: number = 15 * 60; //in seconds
  maxLocationAge: number = 15000; // in milliseconds
  maxTraceSession: number = 24 * 3600 * 100; //in milliseconds
  isOdometerEnabled: boolean = true;
  retriesBeforeFallback: number = 1;
  httpFailureLimit: number = 5;
  dataSendDelay: number = 30000; // in milli seconds
  alarmTime: number = 60000; // in milli seconds
  missingSeqCheckDuration: number = 5 * 60 * 1000; // in milli seconds
  odometerPushFrequency: number = 5 * 60 * 1000; // in milli seconds
  qosLevel: number = 1; // values can be 0 ,1
}
﻿
Configuration Parameters
Parameter
Type
Default Value
Description
locationFrequency
number
10000
Time interval (in ms) for location updates.
distanceAccuracyLimit
number
250
Accuracy threshold in meters.
speedLimit
number
28
Maximum speed threshold in meters per second.
mode
enum
HYBRID
MTS operation mode (HYBRID, GPS_ONLY, etc.).
environment
enum
DEV
SDK environment (DEV or PROD).
batchSize
number
25
Number of location events sent per batch.
isMqttCleanSession
boolean
true
Determines whether MQTT uses a clean session.
mqttKeepAliveInterval
number
900 (15 min)
MQTT keep-alive interval in seconds.
maxLocationAge
number
15000
Maximum allowed location age in milliseconds.
maxTraceSession
number
8640000
Maximum session duration in milliseconds.
isOdometerEnabled
boolean
true
Enables odometer tracking.
retriesBeforeFallback
number
1
Number of retry attempts before fallback.
httpFailureLimit
number
5
Number of failed HTTP requests before stopping.
dataSendDelay
number
30000
Delay before sending data (milliseconds).
alarmTime
number
60000
Alarm trigger time in milliseconds.
missingSeqCheckDuration
number
300000 (5 min)
Interval for checking missing sequences (milliseconds).
odometerPushFrequency
number
300000 (5 min)
Frequency of odometer updates (milliseconds).
qosLevel
number
1
MQTT Quality of Service level (0 or 1).
When to Modify These Defaults?
If your application requires more frequent location updates, reduce locationFrequency.
To improve accuracy, adjust distanceAccuracyLimit.
If battery optimization is a concern, increase dataSendDelay to reduce network usage.
Step 4: Check For Mandatory MTS Permissions
Ensure that mandatory permissions are granted before using MTS SDK:
JS
let granted = await MtsLib.requestPermissionsForMTS();
// if granted = true : all permissions granted
// granted = false : one or more permissions denied
let granted = await MtsLib.requestPermissionsForMTS();
// if granted = true : all permissions granted
// granted = false : one or more permissions denied
﻿
Step 5: Initializing MTS
JS
import type { MTSInitRequest } from '@os1-platform/mts-mobile';

let mtsDefaults = new MtsLib.MTSDefaults();
mtsDefaults.speedLimit = 5000;
mtsDefaults.locationFrequency = 10000;
mtsDefaults.environment = MtsLib.MTSEnv.PRE_PROD;
mtsDefaults.isOdometerEnabled = false;

//Change MTS default values as per your use case

// ...Use this for Initiating MTS
let mtsInitReq: MTSInitRequest = {
  appName: 'app_name',
  appVersion: '1',
  mtsDeviceID: 'deviceId', // Use a unique device ID here
  configData: mtsDefaults,
  baseURL: 'https://{tenant}.example.io/{mtsEndpoint}',
  accessToken: 'token',
  tenantID: 'TENANTID',
};
MtsLib.initMTS(mtsInitReq, async () => {
  // fetch latest token and return the lastest access token
  return 'newToken';
});
import type { MTSInitRequest } from '@os1-platform/mts-mobile';

let mtsDefaults = new MtsLib.MTSDefaults();
mtsDefaults.speedLimit = 5000;
mtsDefaults.locationFrequency = 10000;
mtsDefaults.environment = MtsLib.MTSEnv.PRE_PROD;
mtsDefaults.isOdometerEnabled = false;

//Change MTS default values as per your use case

// ...Use this for Initiating MTS
let mtsInitReq: MTSInitRequest = {
  appName: 'app_name',
  appVersion: '1',
  mtsDeviceID: 'deviceId', // Use a unique device ID here
  configData: mtsDefaults,
  baseURL: 'https://{tenant}.example.io/{mtsEndpoint}',
  accessToken: 'token',
  tenantID: 'TENANTID',
};
MtsLib.initMTS(mtsInitReq, async () => {
  // fetch latest token and return the lastest access token
  return 'newToken';
});
﻿
See Error Codes for Possible error types.
1. Start Event
JS
let startReq: MTSStartRequest = {
  accessToken: 'token', // update access token
  resetSequence: false,
  dispatchID: '12345', // pass dispatch ID here
  expiryTime: Date.now() + 24 * 2600 * 1000, // expiry time after which MTS will stop automatically
};
await MtsLib.startMTS(startReq);
let startReq: MTSStartRequest = {
  accessToken: 'token', // update access token
  resetSequence: false,
  dispatchID: '12345', // pass dispatch ID here
  expiryTime: Date.now() + 24 * 2600 * 1000, // expiry time after which MTS will stop automatically
};
await MtsLib.startMTS(startReq);
﻿
2. Publish Event
JS
await MtsLib.publishEvent('TESTEVENT', { battery: 56, network: 100 });
await MtsLib.publishEvent('TESTEVENT', { battery: 56, network: 100 });
﻿
3. Stop Event
JS
await MtsLib.stopMTS();
await MtsLib.stopMTS();
﻿
4. Flush MTS traces data 
JS
// Call this function to flush MTS traces data
fun flushTracesData() 
// Call this function to flush MTS traces data
fun flushTracesData() 
﻿
Error Codes
PERMISSIONS_ERROR[2500] = "Mandatory Android Permissions not provided"
MTS_INIT_ERROR[2501] ="MTS INIT Not called! MTS Device ID is Empty"
PARAM_MISSING[2502] = "Mandatory Paramater is missing in request"
MTS Geofencing Introduction
MTS SDK provides a real-time geofencing feature that:
Tracks user ENTRY/EXIT events
Syncs geofence events to the server in real-time
Works in the background even if the app is killed
Starting Geofencing Process
Geofencing process can only be started post calling "startMTS()" in your code. Whenever a geofence event is captured by MTS SDK. It will perform two actions:
It will emit an event referring to a Geofence ENTRY/ EXIT to the integrating application.
It will add an EVENT object to the existing MTS traces object.
Note: Ensure MTS service is running before calling startGeofence().
Step 1: Start Geofencing Process
Ensure MTS service is running before calling startGeofence().
JS
fun startGeofence(
    accessToken: String, // user access token 
    geofenceRef: String?, // geofence ref corresponding to an active geofencing process
    abortExisting: Boolean, // pass as true or false if you want to abort the existing geofence process and start a new one
    geoJSON: String, // geoJSON referrring to a geofence
    meta: String? // any context related data that you want in the EXIT/ ENTRY event callback or in the event that will be sent to existing MTS traces.
) : string
fun startGeofence(
    accessToken: String, // user access token 
    geofenceRef: String?, // geofence ref corresponding to an active geofencing process
    abortExisting: Boolean, // pass as true or false if you want to abort the existing geofence process and start a new one
    geoJSON: String, // geoJSON referrring to a geofence
    meta: String? // any context related data that you want in the EXIT/ ENTRY event callback or in the event that will be sent to existing MTS traces.
) : string
﻿
Step 2: Call startGeofence() function:
JS
//create a geoJSON
let geoJsonData = {
  type: "Feature",
  geometry: {
    type: "Point",
    coordinates: [125.6, 10.1] // 1st index is longitude, 2nd index is latitude
  },
  properties: {
    radius: 5.0
  }
};
//Pass any string identifier as geofenceRef. This can be an empty string or any value you want to refer later in your code as this will correspond to an active geofence process once the startGeofence() is called.
let geofenceRef : string = "";

let ref = 
await startGeofence(Auth.accessToken, geofenceRef, true, JSON.stringify(geoJsonData), "this is meta");  

//This "ref" will refer to a "geofenceRef" corresponding to a freshly started geofencing process.
//create a geoJSON
let geoJsonData = {
  type: "Feature",
  geometry: {
    type: "Point",
    coordinates: [125.6, 10.1] // 1st index is longitude, 2nd index is latitude
  },
  properties: {
    radius: 5.0
  }
};
//Pass any string identifier as geofenceRef. This can be an empty string or any value you want to refer later in your code as this will correspond to an active geofence process once the startGeofence() is called.
let geofenceRef : string = "";

let ref = 
await startGeofence(Auth.accessToken, geofenceRef, true, JSON.stringify(geoJsonData), "this is meta");  

//This "ref" will refer to a "geofenceRef" corresponding to a freshly started geofencing process.
﻿
Important Note About startGeofence() function call:
Ensure that the MTS service is running before calling startGeofence(). Always invoke startMTS() first to start the MTS process before initiating geofencing.
If startGeofence() is called again with the same geofenceRef value and abortExisting set to true, the existing geofence process will be terminated, and a new geofence process will be initiated with the same geofenceRef.
Step 3: Abort Geofencing Process
JS
fun abortGeofence(geofenceRef: String) // geofence ref corresponding to an active geofencing process

//Call abortGeofence() function
await abortGeofence("00091d1c-aff2-46f7-bc5a-f95f45622d01 ") 

//"00091d1c-aff2-46f7-bc5a-f95f45622d01" is the geofenceRef returned from startGeofence() function
fun abortGeofence(geofenceRef: String) // geofence ref corresponding to an active geofencing process

//Call abortGeofence() function
await abortGeofence("00091d1c-aff2-46f7-bc5a-f95f45622d01 ") 

//"00091d1c-aff2-46f7-bc5a-f95f45622d01" is the geofenceRef returned from startGeofence() function
﻿
Step 4: Check Geofencing Process Status
JS
fun checkGeofenceStatus(geofenceRef: String) : string // geofence ref corresponding to an active geofencing process

//Call checkGeofenceStatus() function
await checkGeofenceStatus("00091d1c-aff2-46f7-bc5a-f95f45622d01") 

//"00091d1c-aff2-46f7-bc5a-f95f45622d01" is the geofenceRef returned from startGeofence() function call.


//Expected return values from checkGeofenceStatus() function call can be: 
//1. "ON-GOING"
//2. "ABORTED"
//3. "NO_STATUS_FOUND" // will be returned when no row exists against geofenceRef passed as param
fun checkGeofenceStatus(geofenceRef: String) : string // geofence ref corresponding to an active geofencing process

//Call checkGeofenceStatus() function
await checkGeofenceStatus("00091d1c-aff2-46f7-bc5a-f95f45622d01") 

//"00091d1c-aff2-46f7-bc5a-f95f45622d01" is the geofenceRef returned from startGeofence() function call.


//Expected return values from checkGeofenceStatus() function call can be: 
//1. "ON-GOING"
//2. "ABORTED"
//3. "NO_STATUS_FOUND" // will be returned when no row exists against geofenceRef passed as param
﻿
Possible return values:
"ON-GOING"
"ABORTED"
"NO_STATUS_FOUND"
Geofence Event Updates
When a user enters/exits a geofence, the SDK:
Emits an event to the integrating application:
GEOFENCE_ENTRY: User enters geofence
GEOFENCE_EXIT: User exits geofence
Adds an event object to the MTS traces object
Example Event Object
JS
//Event Object
"event": {
    "data": {
      "distance": 0,
      "meta": "this is meta", //meta, passed as param in the startGeofence() function
      "timestamp": 1731391176014
    },
    "name": "GEOFENCE_ENTRY" //name of the geofence ENTRY/ EXIT event
  }


//Complete Trace object with "event" object added
{
  "event": {
    "data": {
      "distance": 0,
      "meta": "this is meta1",
      "timestamp": 1731391176014
    },
    "name": "GEOFENCE_ENTRY"
  },
  "app": "OS1 Driver App",
  "id": [
    ""
  ],
  "seq": 3,
  "tis": 1731391176026,
  "accuracy": 600,
  "distance": 0,
  "isMobile": true, //This key is newly added. And will be sent to all the MTS traces.
  "lat": 37.422094,
  "lon": -122.083922,
  "provider": "network",
  "speed": 0
}   
//Event Object
"event": {
    "data": {
      "distance": 0,
      "meta": "this is meta", //meta, passed as param in the startGeofence() function
      "timestamp": 1731391176014
    },
    "name": "GEOFENCE_ENTRY" //name of the geofence ENTRY/ EXIT event
  }


//Complete Trace object with "event" object added
{
  "event": {
    "data": {
      "distance": 0,
      "meta": "this is meta1",
      "timestamp": 1731391176014
    },
    "name": "GEOFENCE_ENTRY"
  },
  "app": "OS1 Driver App",
  "id": [
    ""
  ],
  "seq": 3,
  "tis": 1731391176026,
  "accuracy": 600,
  "distance": 0,
  "isMobile": true, //This key is newly added. And will be sent to all the MTS traces.
  "lat": 37.422094,
  "lon": -122.083922,
  "provider": "network",
  "speed": 0
}   
﻿
Listening Geofence Events
How to listen a geofence event on application end whenever an ENTRY/ EXIT event occurs:

Events Constants:
  1. GEOFENCE_ENTRY
  2. GEOFENCE_EXIT
JS
//listening entry event
DeviceEventEmitter.addListener("GEOFENCE_ENTRY", (data) => {
  //You can perform any action based on the values you get from data object
  //"data" is a concatenated string in the format "geofencingRef#$meta"

  //Destructure the data string using split() function
  const [geofencingRef, meta] = data.split("#");
    
  // Now you have the two parts in separate variables
  console.log(geofencingRef); // "$geofencingRef"
  console.log(meta);          // "$meta"      

  //1. "geofenceRef" - that was passed into the startGeofence() function call
  //2. "meta" - that was passed into the startGeofence() function call
  console.log("Received event : GEOFENCE_ENTRY::geofenceRef = ", geofenceRef);
  console.log("Received event : GEOFENCE_ENTRY::meta = ", meta);
});

//listening exit event
DeviceEventEmitter.addListener("GEOFENCE_EXIT", (data) => {
  //You can perform any action based on the values you get from data object
  //"data" is a concatenated string in the format "geofencingRef#$meta"

  //Destructure the data string using split() function
  const [geofencingRef, meta] = data.split("#");
    
  // Now you have the two parts in separate variables
  console.log(geofencingRef); // "$geofencingRef"
  console.log(meta);          // "$meta"      

  //1. "geofenceRef" - that was passed into the startGeofence() function call
  //2. "meta" - that was passed into the startGeofence() function call
  console.log("Received event : GEOFENCE_EXIT::geofenceRef = ", geofenceRef);
  console.log("Received event : GEOFENCE_EXIT::meta = ", meta);
});
//listening entry event
DeviceEventEmitter.addListener("GEOFENCE_ENTRY", (data) => {
  //You can perform any action based on the values you get from data object
  //"data" is a concatenated string in the format "geofencingRef#$meta"

  //Destructure the data string using split() function
  const [geofencingRef, meta] = data.split("#");
    
  // Now you have the two parts in separate variables
  console.log(geofencingRef); // "$geofencingRef"
  console.log(meta);          // "$meta"      

  //1. "geofenceRef" - that was passed into the startGeofence() function call
  //2. "meta" - that was passed into the startGeofence() function call
  console.log("Received event : GEOFENCE_ENTRY::geofenceRef = ", geofenceRef);
  console.log("Received event : GEOFENCE_ENTRY::meta = ", meta);
});

//listening exit event
DeviceEventEmitter.addListener("GEOFENCE_EXIT", (data) => {
  //You can perform any action based on the values you get from data object
  //"data" is a concatenated string in the format "geofencingRef#$meta"

  //Destructure the data string using split() function
  const [geofencingRef, meta] = data.split("#");
    
  // Now you have the two parts in separate variables
  console.log(geofencingRef); // "$geofencingRef"
  console.log(meta);          // "$meta"      

  //1. "geofenceRef" - that was passed into the startGeofence() function call
  //2. "meta" - that was passed into the startGeofence() function call
  console.log("Received event : GEOFENCE_EXIT::geofenceRef = ", geofenceRef);
  console.log("Received event : GEOFENCE_EXIT::meta = ", meta);
});
﻿
Flush Geofence DB
JS
//Call this function to flush DB data related to entire geofencing processes
fun flushGeofenceData()
//Call this function to flush DB data related to entire geofencing processes
fun flushGeofenceData()
﻿
Geofence Error Codes
START_GEOFENCE_ERROR_CODE[2507] = "Geofence start failed. Please try again".
CHECK_GEOFENCE_STATUS_ERROR_CODE[2508] = "Geofence status check failed. Please try again". 
ABORT_GEOFENCE_ERROR_CODE[2509] = "Geofence abort failed. Please try again". 
FLUSH_GEOFENCE_ERROR_CODE[2510] = "Geofence data flush failed. Please try again".
﻿
Parameter	Type	Default Value	Description
locationFrequency	number	10000	Time interval (in ms) for location updates.
distanceAccuracyLimit	number	250	Accuracy threshold in meters.
speedLimit	number	28	Maximum speed threshold in meters per second.
mode	enum	HYBRID	MTS operation mode (HYBRID, GPS_ONLY, etc.).
environment	enum	DEV	SDK environment (DEV or PROD).
batchSize	number	25	Number of location events sent per batch.
isMqttCleanSession	boolean	true	Determines whether MQTT uses a clean session.
mqttKeepAliveInterval	number	900 (15 min)	MQTT keep-alive interval in seconds.
maxLocationAge	number	15000	Maximum allowed location age in milliseconds.
maxTraceSession	number	8640000	Maximum session duration in milliseconds.
isOdometerEnabled	boolean	true	Enables odometer tracking.
retriesBeforeFallback	number	1	Number of retry attempts before fallback.
httpFailureLimit	number	5	Number of failed HTTP requests before stopping.
dataSendDelay	number	30000	Delay before sending data (milliseconds).
alarmTime	number	60000	Alarm trigger time in milliseconds.
missingSeqCheckDuration	number	300000 (5 min)	Interval for checking missing sequences (milliseconds).
odometerPushFrequency	number	300000 (5 min)	Frequency of odometer updates (milliseconds).
qosLevel	number	1	MQTT Quality of Service level (0 or 1).
SDK Overview
Dispatch SDK