MTS SDK

introduction movement tracking system docid\ ehihv0zwowjnvh5q3gapc 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 npm install @os1 platform/mts mobile step 2 import mts sdk import mts sdk in your project 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) 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 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 let granted = await mtslib requestpermissionsformts(); // if granted = true all permissions granted // granted = false one or more permissions denied step 5 initializing mts 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 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 await mtslib publishevent('testevent', { battery 56, network 100 }); 3\ stop event await mtslib stopmts(); 4\ flush mts traces data // 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() 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 //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 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 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 //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 //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 //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"