Skip to main content

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

NameTypeRequiredDescriptionDefault
enableHighAccuracybooleannoProvides 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
timeoutnumbernoThe 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.
maximumAgenumbernoAccept 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

NameTypeDescription
errstringerror string, null when operation is successful
positionobjectRetrieved geolocation position

position

NameTypeDescription
coordsobjectObject containing coordinates
timestampnumberLocation timestamp
isBackgroundbooleanIndicates whether location was captured in background
position.coords
NameTypeDescription
accuracynumberLocation estimated accuracy in meters
latitudenumberLocation latitude
longitudenumberLocation longitude
altitudenumberLocation altitude
altitudeAccuracynumberAltitude accuracy
speednumberMovement speed if device is moving
headingnumberMovement 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

NameTypeRequiredDescriptionDefault
enableHighAccuracybooleannoProvides 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
timeoutnumbernoThe 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.
maximumAgenumbernoAccept 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.

NameTypeDescription
watchIdnumberRemember the watchId so that you can stop watching position later.
coordsobjectSee position.coords
timestampnumberLocation timestamp
isBackgroundbooleanIndicates 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

NameTypeRequiredDescriptionDefault
watchIdnumberyesThe 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

NameTypeRequiredDescriptionDefault
sessionIdstringyesSpecifies the session ID
passcodestringyesSpecifies the passcode of the session
titlestringnoYou can specify a title for the newly created session
expiresOndateyes if maxDuration is not providedDate that specifies when the session will expire
maxDurationnumberyes if expiresOn is not providedSpecifies the number of milliseconds that the session will live
users[object]noSpecifies the session users

users

NameTypeRequiredDescriptionDefault
userTokenstringnoSpecifies the user token.
metadataobjectnoAny metadata that you would like to attach to the user.

callback(err, session)

Callback function after the session has been created

NameTypeDescription
errstringerror string, null when operation is successful.
sessionobjectThe newly created session.

session

NameTypeDescription
sessionIdstringCreated session ID.
titlestringCreated session title.
expiresOndateDate that indicates when the session will expire.
isExpiredbooleanBoolean 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

NameTypeRequiredDescriptionDefault
sessionIdstringyesSpecifies the desired session ID.

callback(err, session)

Callback function after the session has been retrieved

NameTypeDescription
errstringerror string, null when operation is successful.
sessionobjectSee session

users

NameTypeDescription
userTokenstringUser access token
isTrackablebooleanBoolean value indicates if the user is trackable or not
metadataobjectmetadata previously attached to user
gpsLocationobjectLast captured GPS location for user (can be null). See Location
homeLocationobjectLast saved home profile address (can be null). value may fallback to user IP address if address is not present. See Location
lastLocationobjectThe 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. User Location Tracking

location

NameTypeDescription
lastUpdatedOndateDate indicates when the user's location was last updated
positionobjectObject containing user's last location

position

NameTypeDescription
coordinatesarrayArray 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

NameTypeRequiredDescriptionDefault
sessionIdstringyesSpecifies the desired session ID
passcodestringyesalways provide the passcode to add self or others
users[object]yesArray of users to be added to the session

users

NameTypeRequiredDescriptionDefault
userTokenstringyesSpecifies the user token
metadataobjectnometadata previously attached to the user

callback(err, result)

Callback function after users have been added to the session

NameTypeDescription
errstringerror string, null when operation is successful
resultobjectObject 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

NameTypeRequiredDescriptionDefault
sessionIdstringyesSpecifies the desired session ID
users[object]yesArray of users to be removed from the session

users

NameTypeRequiredDescriptionDefault
userTokenstringyesSpecifies the user token
metadataobjectnometadata previously attached to the user

callback(err, result)

Callback function after users have been removed from the session

NameTypeDescription
errstringerror string, null when operation is successful
resultobjectObject 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

NameTypeRequiredDescriptionDefault
sessionIdstringyesSpecifies the desired session ID
expiresOndateyes if maxDuration is not providedDate that specifies when the session should expire
maxDurationnumberyes if expiresOn is not providedSpecifies the number of milliseconds that the session should live
titlestringnoYou have the option to change the session title

callback(err, result)

Callback function after the session has been updated

NameTypeDescription
errstringerror string, null when operation is successful.
resultobjectObject 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

NameTypeRequiredDescriptionDefault
sessionIdstringyesSpecifies the desired session ID

callback(err, result)

Callback function after one or more users location gets updated

NameTypeDescription
errstringerror string, null when operation is successful
resultobjectThe updated session with the watchId

result

Object containing session and watchId.

NameTypeDescription
watchIdstringRemember the watchId so that you can stop watching session later
sessionobjectSee session

stopWatch()

Stop session watch.

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

options

NameTypeRequiredDescriptionDefault
watchIdstringyesThe watchId you were given in the callback of startWatch

callback(err, result)

Callback function after one or more users location gets updated

NameTypeDescription
errstringerror string, null when operation is successful
resultobjectObject 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

NameTypeRequiredDescriptionDefault
sessionIdstringyesSpecifies the desired session ID

callback(err, result)

Callback function after the session has been deleted

NameTypeDescription
errstringerror string, null when operation is successful
resultobjectObject 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

NameTypeDescription
errstringerror 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

NameTypeRequiredDescriptionDefault
sessionIdstringyesSpecifies the desired session ID

callback(err, result)

Callback function after the tracking has been enabled

NameTypeDescription
errstringerror string, null when operation is successful
resultobjectObject 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

NameTypeRequiredDescriptionDefault
sessionIdstringyesSpecifies the desired session ID

callback(err, result)

Callback function after the tracking has been disabled

NameTypeDescription
errstringerror string, null when operation is successful
resultobjectObject 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:

CodeDescription
invalidUserTokenInvalid user token
userAlreadyExistsInGeoSessionUser already exists in geo session
geoSessionExistsGeo session already exists
geoSessionExpiredReturned when using session.get for an expired session
notFoundGeo 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

NameTypeRequiredDescriptionDefault
maximumDurationnumbernoSpecifies 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

NameTypeDescription
errstringerror string, null when operation is successful.
resultobjectObject 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

NameTypeRequiredDescriptionDefault
levelstringnoSpecifies the watch level, whether it is app or plugin level.app

callback(err, result)

Callback function after checking if tracking is active

NameTypeDescription
errstringerror string, null when operation is successful.
resultobjectObject 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

NameTypeDescription
errstringerror string, null when operation is successful.
resultobjectObject containing the boolean value isSuccessful, indicating the success of the operation.