buildfire.geo

This service lets you access users location. It helps request and watch the location of the device.

Methods

getCurrentPosition()

buildfire.geo.getCurrentPosition(options, callback)

Gets the device current location

buildfire.geo.getCurrentPosition(null, (err, position) => {
  if (err) return console.error(err);

  console.log("Lat", position.coords.latitude);
  console.log("Lng", position.coords.longitude);
});

options

Name	Type	Required	Description	Default
enableHighAccuracy	boolean	no	Provides a hint that the application needs the best possible results. By default, the device attempts to retrieve a Position using network-based methods. Setting this property to true tells the framework to use more accurate methods, such as satellite positioning.	false
timeout	number	no	The maximum length of time (milliseconds) that is allowed to pass from the call to getCurrentPosition until the success callback executes. If the success callback is not invoked within this time, the error callback is passed a PositionError.TIMEOUT error code.
maximumAge	number	no	Accept a cached position whose age is no greater than the specified time in milliseconds.

callback(err, position)

Callback function after the geolocation has been retrieved

Name	Type	Description
err	string	error string, null when operation is successful
position	object	Retrieved geolocation position

position

Name	Type	Description
coords	object	Object containing coordinates
timestamp	number	Location timestamp
isBackground	boolean	Indicates whether location was captured in background

position.coords

Name	Type	Description
accuracy	number	Location estimated accuracy in meters
latitude	number	Location latitude
longitude	number	Location longitude
altitude	number	Location altitude
altitudeAccuracy	number	Altitude accuracy
speed	number	Movement speed if device is moving
heading	number	Movement direction as angle

---

watchPosition()

buildfire.geo.watchPosition(options, callback)

Allows you to watch the devices location and will trigger every time a location change occurs

buildfire.geo.watchPosition({ timeout: 30000 }, (position) => {
  console.log("Position changed");
  console.log("New Lat", position.coords.latitude);
  console.log("New Lng", position.coords.longitude);
});

tip

You can use watchPosition in combination with background service to track users position in background. Note that additional item BackgroundGeo is needed in plugin.json file.

options

Name	Type	Required	Description	Default
enableHighAccuracy	boolean	no	Provides a hint that the application needs the best possible results. By default, the device attempts to retrieve a Position using network-based methods. Setting this property to true tells the framework to use more accurate methods, such as satellite positioning.	false
timeout	number	no	The maximum length of time (milliseconds) that is allowed to pass from the call to geolocation.watchPosition until the corresponding success callback executes. If the success callback is not invoked within this time, the error callback is passed a PositionError.TIMEOUT error code. When used in conjunction with geolocation.watchPosition, the error callback will be called on an interval every timeout milliseconds.
maximumAge	number	no	Accept a cached position whose age is no greater than the specified time in milliseconds.

callback(position)

Callback function triggered every time a location change occurs on device

position

Object containing position and watchId.

Name	Type	Description
watchId	number	Remember the watchId so that you can stop watching position later.
coords	object	See position.coords
timestamp	number	Location timestamp
isBackground	boolean	Indicates whether location was captured in background

---

clearWatch()

buildfire.geo.clearWatch(watchId, callback)

Stops watching the location changes of the device

buildfire.geo.clearWatch(1, () => {
  console.log("Stopped watching position");
});

watchId

The id you were given in the callback of watchPosition

Name	Type	Required	Description	Default
watchId	number	yes	The id you were given in the callback of watchPosition.

callback()

Optional callback function that is called when the watcher is cleared

---

Session

Sessions serve as a dynamic mechanism for grouping users, providing the flexibility to dynamically add or remove users while monitoring changes in their positions. It is an efficient way for tracking the last known positions of users.

create()

buildfire.geo.session.create(options, callback)

Create a session

let tripEndDate = new Date();
tripEndDate.setDate(tripEndDate.getDate() + 3);
buildfire.geo.session.create({
    sessionId: 'family-hiking-trip',
    passcode: 'hicking@grandcanyon',
    title: 'HIKING TRIP',
    expiresOn: tripEndDate,
},
    (err, session) => {
        console.log("Created session: ", session.sessionId);
    }
);

options

Name	Type	Required	Description	Default
sessionId	string	yes	Specifies the session ID
passcode	string	yes	Specifies the passcode of the session
title	string	no	You can specify a title for the newly created session
expiresOn	date	yes if maxDuration is not provided	Date that specifies when the session will expire
maxDuration	number	yes if expiresOn is not provided	Specifies the number of milliseconds that the session will live
users	[object]	no	Specifies the session users

users

Name	Type	Required	Description	Default
userToken	string	no	Specifies the user token.
metadata	object	no	Any metadata that you would like to attach to the user.

callback(err, session)

Callback function after the session has been created

Name	Type	Description
err	string	error string, null when operation is successful.
session	object	The newly created session.

session

Name	Type	Description
sessionId	string	Created session ID.
title	string	Created session title.
expiresOn	date	Date that indicates when the session will expire.
isExpired	boolean	Boolean value indicates if the session has expired or not.
users	[object]	Array of users added to the session and their last known location.

---

get()

buildfire.geo.session.get(options, callback)

Returns session details, containing session users information along with their respective last known locations, and the date of the latest position update

buildfire.geo.session.get({ sessionId: 'family-hiking-trip' }, (err, session) => {
  console.log("Session title: ", session.title);
  session.users.forEach(user => {
    console.log(`user ${user.userToken} last known location:
     lat: ${user.lastLocation?.position?.coordinates[1]}, 
     lng: ${user.lastLocation?.position?.coordinates[0]}`);
  })
});

options

Name	Type	Required	Description	Default
sessionId	string	yes	Specifies the desired session ID.

callback(err, session)

Callback function after the session has been retrieved

Name	Type	Description
err	string	error string, null when operation is successful.
session	object	See session

users

Name	Type	Description
userToken	string	User access token
isTrackable	boolean	Boolean value indicates if the user is trackable or not
metadata	object	metadata previously attached to user
gpsLocation	object	Last captured GPS location for user (can be null). See Location
homeLocation	object	Last saved home profile address (can be null). value may fallback to user IP address if address is not present. See Location
lastLocation	object	The latest updated location if any (GPS or home) . See Location

Warning

For home location to be saved, home location tracking must be enabled in Control Panel > Security > Login Screen > Settings.

location

Name	Type	Description
lastUpdatedOn	date	Date indicates when the user's location was last updated
position	object	Object containing user's last location

position

Name	Type	Description
coordinates	array	Array of two numbers, representing longitude and latitude

---

addUsers()

buildfire.geo.session.addUsers(options, callback)

The session creator and all users within the session have the capability to add new users to the session.

buildfire.auth.searchUsers(
    {
      searchText: 'John',
      sort: { createdOn: 1},
      limit: 10,
    },
    (err, searchResult) => {
      if (!searchResult || !searchResult.length) return console.log('Change "searchText" to find a user.');
      buildfire.geo.session.addUsers({ 
        sessionId: 'family-hiking-trip',
        passcode: 'hicking@grandcanyon',
        users: [
          {
            userToken: searchResult[0].userToken,
            metadata: {carType: 'MERCEDES-BENZ G-CLASS'}
          }]
        },
        (err, result) => {
          if(err) return console.error(err);
          console.log("is user added: ", result.isSuccessful);
      });
    }
  );

options

Name	Type	Required	Description	Default
sessionId	string	yes	Specifies the desired session ID
passcode	string	yes	always provide the passcode to add self or others
users	[object]	yes	Array of users to be added to the session

users

Name	Type	Required	Description	Default
userToken	string	yes	Specifies the user token
metadata	object	no	metadata previously attached to the user

callback(err, result)

Callback function after users have been added to the session

Name	Type	Description
err	string	error string, null when operation is successful
result	object	Object containing the boolean value isSuccessful, indicating the success of the operation

---

removeUsers()

buildfire.geo.session.removeUsers(options, callback)

The session creator and all users within the session have the capability to remove users from the session.

buildfire.auth.searchUsers(
  {
    searchText: 'John',
    sort: { createdOn: 1},
    limit: 10,
  },
  (err, searchResult) => {
    if (!searchResult || !searchResult.length) return console.log('Change "searchText" to find a user.');  
    buildfire.geo.session.removeUsers({ 
      sessionId: 'family-hiking-trip',
      users: [
        {
          userToken: searchResult[0].userToken,
          metadata: {carType: 'MERCEDES-BENZ G-CLASS'}
        }]
      },
      (err, result) => {
        if(err) return console.error(err);
        console.log("is user removed: ", result.isSuccessful);
    });
  }
  );

options

Name	Type	Required	Description	Default
sessionId	string	yes	Specifies the desired session ID
users	[object]	yes	Array of users to be removed from the session

users

Name	Type	Required	Description	Default
userToken	string	yes	Specifies the user token
metadata	object	no	metadata previously attached to the user

callback(err, result)

Callback function after users have been removed from the session

Name	Type	Description
err	string	error string, null when operation is successful
result	object	Object containing the boolean value isSuccessful, indicating the success of the operation

---

updateInfo()

buildfire.geo.session.updateInfo(options, callback)

Update the session's expiresOn or maxDuration.

buildfire.geo.session.updateInfo({ sessionId: 'family-hiking-trip', maxDuration: 3600000 },
  (err, result) => {
    console.log("is session updated: ", result.isSuccessful);
});

options

Name	Type	Required	Description	Default
sessionId	string	yes	Specifies the desired session ID
expiresOn	date	yes if maxDuration is not provided	Date that specifies when the session should expire
maxDuration	number	yes if expiresOn is not provided	Specifies the number of milliseconds that the session should live
title	string	no	You have the option to change the session title

callback(err, result)

Callback function after the session has been updated

Name	Type	Description
err	string	error string, null when operation is successful.
result	object	Object containing the boolean value isSuccessful, indicating the success of the operation.

---

startWatch()

buildfire.geo.session.startWatch(options, callback)

Start watching previously created session; the callback function is triggered each time there is a change in the position of a user within the session, returns the updated session with watchId, which can be used later to stop the watch

buildfire.geo.session.startWatch({ sessionId: 'family-hiking-trip' }, (err, result) => {
  console.log("Session watch ID: ", result.watchId);
  result.session.users.forEach(user => {
    console.log(`user ${user.userToken} last known location:
     lat: ${user.gpsLocation?.position?.coordinates[1]}, 
     lng: ${user.gpsLocation?.position?.coordinates[0]}`);
  });
});

options

Name	Type	Required	Description	Default
sessionId	string	yes	Specifies the desired session ID

callback(err, result)

Callback function after one or more users location gets updated

Name	Type	Description
err	string	error string, null when operation is successful
result	object	The updated session with the watchId

result

Object containing session and watchId.

Name	Type	Description
watchId	string	Remember the watchId so that you can stop watching session later
session	object	See session

---

stopWatch()

Stop session watch.

buildfire.geo.session.stopWatch({ watchId: 'watchId' }, (err, result) => {
   console.log("is stopped watching session", result.isSuccessful);
});

options

Name	Type	Required	Description	Default
watchId	string	yes	The watchId you were given in the callback of startWatch

callback(err, result)

Callback function after one or more users location gets updated

Name	Type	Description
err	string	error string, null when operation is successful
result	object	Object containing the boolean value isSuccessful, indicating the success of the operation

---

delete()

buildfire.geo.session.delete(options, callback)

Deletes a session.

buildfire.geo.session.delete({ sessionId: 'family-hiking-trip' }, (err, result) => {
  console.log("is session deleted: ", result.isSuccessful);
});

options

Name	Type	Required	Description	Default
sessionId	string	yes	Specifies the desired session ID

callback(err, result)

Callback function after the session has been deleted

Name	Type	Description
err	string	error string, null when operation is successful
result	object	Object containing the boolean value isSuccessful, indicating the success of the operation

---

getCurrentUserSessions()

buildfire.geo.session.getCurrentUserSessions(options, callback)

Retrieves all sessions the user is present in.

buildfire.geo.session.getCurrentUserSessions(null, (err, sessions) => {
  sessions.forEach((session, i) => {
    console.log(i + 1, '- ' +  session.title);
  });
});

callback(err, sessions)

Callback function after the session has been deleted

Name	Type	Description
err	string	error string, null when operation is successful
sessions	[object]	Array of sessions which the user is present in

---

enableTrackability()

buildfire.geo.session.enableTrackability(options, callback)

Allows the user to enable his location tracking.

buildfire.geo.session.enableTrackability({ sessionId: 'family-hiking-trip' },
  (err, result) => {
    console.log("is tracking enabled: ", result.isSuccessful);
});

options

Name	Type	Required	Description	Default
sessionId	string	yes	Specifies the desired session ID

callback(err, result)

Callback function after the tracking has been enabled

Name	Type	Description
err	string	error string, null when operation is successful
result	object	Object containing the boolean value isSuccessful, indicating the success of the operation

---

disableTrackability()

buildfire.geo.session.disableTrackability(options, callback)

Allows the user to disable his location tracking.

buildfire.geo.session.disableTrackability({ sessionId: 'family-hiking-trip' },
  (err, result) => {
    console.log("is tracking disabled: ", result.isSuccessful);
});

options

Name	Type	Required	Description	Default
sessionId	string	yes	Specifies the desired session ID

callback(err, result)

Callback function after the tracking has been disabled

Name	Type	Description
err	string	error string, null when operation is successful
result	object	Object containing the boolean value isSuccessful, indicating the success of the operation

---

Error Status Codes

Errors returned by calling session methods will have one of these codes:

Code	Description
invalidUserToken	Invalid user token
userAlreadyExistsInGeoSession	User already exists in geo session
geoSessionExists	Geo session already exists
geoSessionExpired	Returned when using session.get for an expired session
notFound	Geo Session not found

Examples

let tripEndDate = new Date();
tripEndDate.setDate(tripEndDate.getDate() + 3);
buildfire.geo.session.create({
  sessionId: 'family-hiking-trip',
  title: 'HIKING TRIP',
  passcode: 'hicking@grandcanyon',
  expiresOn: tripEndDate,
  users: []
},
  (err, session) => {
    if (err) return console.error(err);
    console.log("Created session: ", session.sessionId);
    // adding a user to the session 
    buildfire.auth.searchUsers(
      {
        searchText: 'John',
        sort: { createdOn: 1 },
        limit: 10,
      },
      (err, searchResult) => {
        if (!searchResult.length) {
          console.warn('user John not found, try another user name');
          return;
        }
        buildfire.geo.session.addUsers({
          sessionId: 'family-hiking-trip',
          passcode: 'hicking@grandcanyon',
          users: [
            {
              userToken: searchResult[0].userToken,
              metadata: { carType: 'CHEVROLET TAHOE' }
            }]
        },
          (err, result) => {
            console.log("is users added: ", result.isSuccessful);
          });
      }
    );
    // start watching session
    buildfire.geo.session.startWatch({ sessionId: 'family-hiking-trip' },
      (err, result) => {
        console.log("Session watch ID: ", result.watchId);
        result.session.users.forEach(user => {
          if (user.lastLocation) {
            console.log(`User ${user.userToken} last known location:
                         lat: ${user.lastLocation.position.coordinates[1]}, 
                         lng: ${user.lastLocation.position.coordinates[0]}`
            );
          } else {
            console.log(`Tracking is disabled for ${user.userToken}`)
          };
        });
      }
    );
  }
);

Tracking

startTracking()

buildfire.geo.startTracking(options, callback)

Starts tracking user on the current device, sending location to any active session and updates current user profile with each change in position

buildfire.geo.startTracking(null, (err, result) => {
  if (err) return console.error(err);
  console.log('is tracking started: ', result.isSuccessful);
});

options

Name	Type	Required	Description	Default
maximumDuration	number	no	Specifies the maximum duration for tracking in minutes, tracking will stop after this period has been passed.	1 hour

callback(err, result)

Callback function after tracking has been started

Name	Type	Description
err	string	error string, null when operation is successful.
result	object	Object containing the boolean value isSuccessful, indicating the success of the operation.

---

isTracking()

buildfire.geo.isTracking(options, callback)

Checks the status of tracking whether it is currently active or not.

buildfire.geo.isTracking({level: 'plugin'}, (err, result) => {
  if (err) return console.error(err);
  console.log('is tracking started: ', result.isTracking);
});

options

Name	Type	Required	Description	Default
level	string	no	Specifies the watch level, whether it is app or plugin level.	app

callback(err, result)

Callback function after checking if tracking is active

Name	Type	Description
err	string	error string, null when operation is successful.
result	object	Object containing the boolean value isTracking, indicating the state of the tacking operation.

---

stopTracking()

buildfire.geo.stopTracking(options, callback)

Stops tracking the location changes of the device

buildfire.geo.stopTracking(null, (err, result) => {
  if (err) return console.error(err);
  console.log('is tracking stopped: ', result.isSuccessful);
});

callback(err, result)

Callback function after checking if tracking is active

Name	Type	Description
err	string	error string, null when operation is successful.
result	object	Object containing the boolean value isSuccessful, indicating the success of the operation.

---