BuildFire Local Notifications API

buildfire.notifications.localNotification

This is a built in API that allows your widget to schedule local notifications. Note: For existing apps, a hard build is required to add this functionality.

This service requires you to include buildfire/services/notifications/localNotifications.js with your plugin

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

Methods

• checkPermissions(callback): use this method to check if permissions have been granted to the device.

  • callback (err, data): Data is true if the permissions have been granted or false if they have not.

• requestPermission(callback): use this method to request permissions to notifications from the device. First it checks if permissions have been granted to the app. If permissions have already been granted, the callback receives true. If permission haven't yet been granted, it will request permissions. The callback will then receive the value of that request.

  • callback (err, data): callback function called when permissions are accepted or rejected. Data is true if the permissions are granted or false if they are not.

• schedule(options, callback): use to schedule a notification

  • options: object
    • title: string
    • text: string
    • at: Date, representing the time to send the notification.
    • data: object (optional), data that you want to persist for when the notification is clicked or triggered.
    • returnToPluginInstanceId string (optional). The ID of the plugin instance to return to. If the value of 'none' is specified, then it will simply open the app without navigation to a specific plugin.

• callback(err, data): callback function after the notification scheduling is completed. Data contains an id property, which is the id of the newly scheduled notification.

• send(options, callback): use to send a notification immediately

  • options: object
    • title: string
    • text: string
    • data: object (optional), data that you want to persist for when the notification is clicked or triggered.
    • returnToPluginInstanceId string (optional). The ID of the plugin instance to return to. If the value of 'none' is specified, then it will simply open the app without navigation to a specific plugin.

• callback(err, data): callback function after the notification is completed. Data contains an id property, which is the id of the newly scheduled notification.

• cancel(notificationId, callback): use to cancel a scheduled notification.

  • notificationId: The id of the notification that you wish to cancel.
  • callback(err, data): callback function when the notification is canceled. Data contains an id property, which is the id of the newly scheduled notification.

Handlers

• onClick(callback): calls the callback function whenever a local notification is clicked.
  • callback(data): data is an object. It originates from the options.data property which is passed in the schedule call.

Notification Behavior

The iOS and Android operating systems handle notifications slightly different. In iOS a notification only displays when the triggering app is not in focus. In Android the notification is always displayed, regardless of the app being in focus or not. As a result Android users will always see the standard OS notification, while iOS users will only see the standard OS notification when the app is not in focus. To provide a consistent experience across devices the BuildFire local notification API will display a custom dialog for users with iOS, when the app is in focus and the notification is triggered.