Skip to main content

buildfire.notifications.pushNotification

This is a built-in API that allows your control or widget to schedule push notifications to be sent out to devices. If you wish to schedule a Notification to be sent to the device you are currently on use Local Notifications.

Running Example: https://github.com/BuildFire/simpleBuildFireJSExamples/blob/master/examplePushNotifications/widget/index.html

Requirements

Widget

Include pushNotifications.js file in widget header right after the buildfire.min.js

<head>
<!-- ... -->
<script src="../../../scripts/buildfire.min.js"></script>
<script src="../../../scripts/buildfire/services/notifications/pushNotifications.js"></script>
</head>

Control

Include pushNotifications.js file in control header right after the buildfire.min.js

<head>
<!-- ... -->
<script src="../../../../scripts/buildfire.min.js"></script>
<script src="../../../../scripts/buildfire/services/notifications/pushNotifications.js"></script>
</head>

Methods

schedule()

buildfire.notifications.pushNotification.schedule(options, callback)

info

You must subscribe() on the device to receive notifications.

Used to schedule push notification

buildfire.notifications.pushNotification.schedule({
title: "Push notification",
text: "Hello there!",
geoArea: {
radius: 10, // within 10 miles from center
center: {
longitude: 35,
latitude: 35
},
maxLocationAge: 3600 // targets users with location updated within an hour, within that area.
},
},
(err, result) => {
if (err) return console.error(err);

console.log("Push notification scheduled", result);
}
);

options

NameTypeRequiredDescriptionDefault
titlestringyesA short string describing the purpose of the notification
textstringyesPush notification text
inAppMessagestringnoThe HTML text of the message displayed if the push notification is received in app
atDatenoTime to send the push notification atnow
users[string]noArray of userIds to send the push notification to specific users
userTags[string]noArray of user tags to send push notification to users with specific tags
groupNamestringnoSend the push notification to specific groupdefault instance group
queryStringstringnoWill be added to the plugin when the push notification triggers the plugin to open
sendToSelfbooleannoIf false, the device scheduling the push notification will not receive ittrue
geoAreaobjectnoOptions to target users based on their location
options.geoArea
NameTypeRequiredDescriptionDefault
radiusnumberyesSpecifies the targeted circle radius in miles
centerobjectyesSpecifies the circle center point. See center
maxGpsAgestringnoSpecifies the maximum age of a user's GPS location in seconds for targeting. Controls the freshness of GPS location information. Use 0 to include only locations updated at the exact moment of the requestall users regardless of location age
locationModestringnoSpecifies the priority between user's home address and user's last GPS location and which of these addresses to include. Mode can be one of the modes listed in Location ModesGpsOnly
Note

geoArea works only when user location is tracked.

This can be done by the following methods:

Home Location Tracking

Enable home location tracking in Control Panel > Security > Login Screen > Settings.

User Location Tracking

GPS Location Tracking

Enable GPS location tracking by using geo tracker.

options.geoArea.center
NameTypeRequiredDescriptionDefault
longitudenumberyesSpecifies the targeted longitude. must be between (-180 to 180)
latitudenumberyesSpecifies the targeted latitude. must be between (-90 to 90)

callback(err, result)

Callback function after the push notification scheduling is completed.

NameTypeDescription
errstringerror string, null when operation is successful
resultobjectResult contains notificationId, which is the id of the newly scheduled push notification

Location Modes

Location modes that can be used in options.geoArea.locationMode.

ModeDescriptionTracking Required
HomeOnlyHome location must fall within specified radius from center pointHome
GpsOnlyGPS location must fall within specified radius from center pointGPS
HomeAndGpsChecks in both GPS and home locations if any falls within specified radius from center pointAny
HomeIfGpsExpiredFalls back to home location checking only if GPS location age last update is older than the max age or is not set, otherwise only matches GPS location. Useful in cases where last GPS location is only relevant if it is freshBoth Home and GPS

cancel()

buildfire.notifications.pushNotification.cancel(notificationId, callback)

Used to cancel a scheduled push notification

buildfire.notifications.pushNotification.cancel(
"608adde30af35105452a3c96",
(err, isCancelled) => {
if (err) return console.error(err);

console.log("Notification cancelled", isCancelled);
}
);

notificationId

NameTypeRequiredDescriptionDefault
notificationIdstringyesThe id of the notification that you wish to cancel. Can be obtained from schedule result object

callback(err, result)

NameTypeDescription
errstringerror string, null when operation is successful
isCancelledbooleanIndicates whether notification was cancelled successfully

subscribe()

buildfire.notifications.pushNotification.subscribe(options, callback)

Use to subscribe current user to group. You can use this to create custom push notification groups within the app.

buildfire.notifications.pushNotification.subscribe(
{ groupName: "testGroup" },
(err, subscribed) => {
if (err) return console.error(err);

console.log("User subscribed to group", subscribed);
}
);

options

NameTypeRequiredDescriptionDefault
groupNamestringnoName of the group to subscribe user todefault instance group

callback(err, subscribed)

Callback function when the subscription is complete.

NameTypeDescription
errstringerror string, null when operation is successful
subscribedbooleanIndicated whether user was successfully subscribed to group

unsubscribe()

buildfire.notifications.pushNotification.unsubscribe(options, callback)

Use to unsubscribe current user from group.

buildfire.notifications.pushNotification.unsubscribe(
{ groupName: "testGroup" },
(err, unsubscribed) => {
if (err) return console.error(err);

console.log("User unsubscribed from group", unsubscribed);
}
);

options

NameTypeRequiredDescriptionDefault
groupNamestringyesName of the group to subscribe user to

callback(err, unsubscribed)

Callback function when the unsubscription is completed.

NameTypeDescription
errstringerror string, null when operation is successful
unsubscribedbooleanIndicated whether user was successfully unsubscribed from group