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)
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
Name | Type | Required | Description | Default |
---|---|---|---|---|
title | string | yes | A short string describing the purpose of the notification | |
text | string | yes | Push notification text | |
inAppMessage | string | no | The HTML text of the message displayed if the push notification is received in app | |
at | Date | no | Time to send the push notification at | now |
users | [string] | no | Array of userIds to send the push notification to specific users | |
userTags | [string] | no | Array of user tags to send push notification to users with specific tags | |
groupName | string | no | Send the push notification to specific group | default instance group |
queryString | string | no | Will be added to the plugin when the push notification triggers the plugin to open | |
sendToSelf | boolean | no | If false, the device scheduling the push notification will not receive it | true |
geoArea | object | no | Options to target users based on their location |
options.geoArea
Name | Type | Required | Description | Default |
---|---|---|---|---|
radius | number | yes | Specifies the targeted circle radius in miles | |
center | object | yes | Specifies the circle center point. See center | |
maxGpsAge | string | no | Specifies 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 request | all users regardless of location age |
locationMode | string | no | Specifies 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 Modes | GpsOnly |
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.
GPS Location Tracking
Enable GPS location tracking by using geo tracker
.
options.geoArea.center
Name | Type | Required | Description | Default |
---|---|---|---|---|
longitude | number | yes | Specifies the targeted longitude. must be between (-180 to 180) | |
latitude | number | yes | Specifies the targeted latitude. must be between (-90 to 90) |
callback(err, result)
Callback function after the push notification scheduling is completed.
Name | Type | Description |
---|---|---|
err | string | error string, null when operation is successful |
result | object | Result contains notificationId , which is the id of the newly scheduled push notification |
Location Modes
Location modes that can be used in options.geoArea.locationMode
.
Mode | Description | Tracking Required |
---|---|---|
HomeOnly | Home location must fall within specified radius from center point | Home |
GpsOnly | GPS location must fall within specified radius from center point | GPS |
HomeAndGps | Checks in both GPS and home locations if any falls within specified radius from center point | Any |
HomeIfGpsExpired | Falls 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 fresh | Both 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
Name | Type | Required | Description | Default |
---|---|---|---|---|
notificationId | string | yes | The id of the notification that you wish to cancel. Can be obtained from schedule result object |
callback(err, result)
Name | Type | Description |
---|---|---|
err | string | error string, null when operation is successful |
isCancelled | boolean | Indicates 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
Name | Type | Required | Description | Default |
---|---|---|---|---|
groupName | string | no | Name of the group to subscribe user to | default instance group |
callback(err, subscribed)
Callback function when the subscription is complete.
Name | Type | Description |
---|---|---|
err | string | error string, null when operation is successful |
subscribed | boolean | Indicated 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
Name | Type | Required | Description | Default |
---|---|---|---|---|
groupName | string | yes | Name of the group to subscribe user to |
callback(err, unsubscribed)
Callback function when the unsubscription is completed.
Name | Type | Description |
---|---|---|
err | string | error string, null when operation is successful |
unsubscribed | boolean | Indicated whether user was successfully unsubscribed from group |