`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

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`

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`

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`

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

buildfire.notifications.pushNotification

Requirements​

Widget​

Control​

Methods​

schedule() ​

options​

options.geoArea​

Home Location Tracking​

GPS Location Tracking​

options.geoArea.center​

callback(err, result)​

Location Modes​

cancel() ​

notificationId​

callback(err, result)​

subscribe() ​

options​

callback(err, subscribed)​

unsubscribe() ​

options​

callback(err, unsubscribed)​

`buildfire.notifications.pushNotification`

Requirements

Widget

Control

Methods

`schedule()`

`options`

`options.geoArea`

Home Location Tracking

GPS Location Tracking

`options.geoArea.center`

`callback(err, result)`

Location Modes

`cancel()`

`notificationId`

`callback(err, result)`

`subscribe()`

`options`

`callback(err, subscribed)`

`unsubscribe()`

`options`

`callback(err, unsubscribed)`