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);
});
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 |
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. |