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
Note

geoArea works only when user location is tracked.

This can be done by one the following methods:

  • Enabling Location Tracking in Control Panel > Security > Login Screen > Settings tab is enabled.

User Location Tracking

options.geoArea​
NameTypeRequiredDescriptionDefault
radiusnumberyesSpecifies the targeted circle radius in miles.
maxLocationAgestringnoSpecifies the maximum age of users locations in seconds for targeting. Controls the freshness of location information. Use 0 to include only locations updated at the exact moment of the request.all users regardless of location age
centerobjectyesSpecifies the circle center point.
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.

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 subscribtion is completed.

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