Nancy's Preferred Machete

    @awarns/notifications
    TypeScript icon, indicating that this package has built-in type declarations

    1.0.0 • Public • Published

    @awarns/notifications

    npm (scoped) npm

    This module allows to deliver notifications to the user when an event occurs. It also defines some primitives (in form of framework records) to hold possible reactions and interactions of the user with the notification.

    This plugin acts as a wrapper of EddyVerbruggen's NativeScript Local Notifications plugin, adapted to work with the AwarNS Framework task model.

    Install the plugin using the following command line instruction:

    ns plugin add @awarns/notifications

    Usage

    After installing and configuring this plugin, you'll be granted with two interaction mechanisms to work with it:

    1. The plugin API. Through it, you'll be able to manage the notifications which have been delivered and the possible reactions to them.
    2. The notification delivery tasks, which allow to locally display notifications to your users using system's services. Users can tap or discard the notifications. The plugin comes with specific records for direct reactions: the NotificationTap and the NotificationDiscard. It also comes with definitions of records for more specific notification tap actions.

    Setup

    This plugin requires you to register its loader during the framework initialization, like this:

    // ... platform imports
    import { awarns } from '@awarns/core';
    import { demoTasks } from '../tasks';
    import { demoTaskGraph } from '../graph';
    import { registerNotificationsPlugin } from '@awarns/notifications';
    
    awarns
      .init(
        demoTasks,
        demoTaskGraph,
        [
          registerNotificationsPlugin('App notifications'),
        ]
      )
      // ... handle initialization promise

    Plugin loader parameters:

    Parameter Type Description
    notificationsChannelName String Required by the OS. The channel name to be used for the notifications delivered using the framework, so the user can adjust their priority through the system settings

    API

    notificationsManager

    The notificationsManager singleton object allows to manage reactions to notifications. It offers the following actions:

    Method Return type Description
    onNotificationTap(callback: NotificationCallback) Promise<void> Sets a callback in your UI to handle notification taps from the system's tray. If the tap arrives before the callback has been set up, for example, when the app is not running, the tap is cached and will be delivered right after registering the callback
    onNotificationDiscard(callback: NotificationCallback) Promise<void> Sets a callback to receive updates on notifications being discarded from the system's tray
    markAsSeen(id: number) Promise<void> Indicate to the plugin that a notification has been handled / read. It will be removed from the list of pending notifications

    notifications

    The notifications singleton object allows to access the notifications that have been delivered but not yet handled / read. It offers the following actions:

    Method Return type Description
    list() Observable<Array<Notification>> Allows to observe changes in all the unread notifications. More details on the Notification interface, right after this table. It is recommended to install RxJS, to operate with the output of this method
    get(id: string) Promise<Notification> Allows to retrieve a stored notification by its id

    Notification

    Property Type Description
    id number The unique identifier of the notification
    title string The content of notification heading line
    body string (Optional) The notification content
    timestamp Date The moment when the notification was delivered
    tapAction TapAction (Optional) Additional metadata, to know how to handle the notification when tapped

    TapAction

    Property Type Description
    type TapActionType | string The type of action to conduct after the notification tap. See table below, to see some examples
    id string The specific id of the action inside its type
    metadata object Automatically populated. Contains the payload (data) of the event that triggered the execution of the task that sent the notification

    TapActionType

    Option Description
    OPEN_APP Default action, when none is specified. It just opens the app. The notification tap callback does not get invoked when this action type is provided
    OPEN_CONTENT Can be used to indicate that the app must display some content for the user to see it. Check out the related UserReadContent record type
    DELIVER_QUESTIONS Can be used to indicate that the app must deliver some questions for the user to answer. Check out the related QuestionnaireAnswers record type
    ASK_FEEDBACK Can be used to indicate that the app must deliver some quick feedback for the user to answer (single question). Check out the related UserFeedback record type
    ASK_CONFIRMATION Can be used to indicate that the app must deliver some yes/no confirmation question for the user to answer. Check out the related UserConfirmation record type

    Tasks

    Send a notification

    Task name: sendNotification

    Description: Sends a notification with the given information

    Execution requirements: None

    To register this task for its use, you just need to import it and call its generator function inside your application's task list:

    import { Task } from '@awarns/core/tasks';
    import { sendNotificationTask } from '@awarns/notifications';
    
    export const demoTasks: Array<Task> = [
      sendNotificationTask(),
    ];

    Task generator parameters:

    The task generator takes no parameters.

    Task output events:

    This task doesn't produce significant events after it completes its execution, aside from the regular {task-name}Finished event: sendNotificationFinished.

    However, once it has finished running, relevant events will be emitted by the internal listeners. These are listed below.

    Example usage in the application task graph:

    on(
      'startEvent',
      run('sendNotification', {
        title: 'New content available', // All notifications must contain a title
        body: 'This information may be valuable for you', // The body of the notification can be provided through here 
                                                          // or inside the payload (data) of the event trigger, inside a 
                                                          // property called body
        tapAction: { // (Optional) If not provided, defaults to OPEN_APP
          type: TapActionType.OPEN_CONTENT, // See the rest of the options in the TapActionType enum
          id: 'content-1', // For the app to distingish what content must be displayed after tapping the notification
        },
      })
    );
    
    on('notificationTapped', run('writeRecords'));
    on('notificationCleared', run('writeRecords'));

    Note: To use the writeRecords task, the persistence package must be installed and configured. See persistence package docs.

    Send a random notification among a set of options

    Task name: sendRandomNotification

    Description: Sends a random notification among a given set

    Execution requirements: None

    To register this task for its use, you just need to import it and call its generator function inside your application's task list:

    import { Task } from '@awarns/core/tasks';
    import { sendRandomNotificationTask } from '@awarns/notifications';
    
    export const demoTasks: Array<Task> = [
      sendRandomNotificationTask(),
    ];

    Task generator parameters:

    The task generator takes no parameters.

    Task output events:

    This task doesn't produce significant events after it completes its execution, aside from the regular {task-name}Finished event: sendNotificationFinished.

    However, once it has finished running, relevant events will be emitted by the internal listeners. These are listed below.

    Example usage in the application task graph:

    on(
      'startEvent',
      run('sendRandomNotification', {
        options: [
          {
            title: 'Would you like to rate the app?', // All notifications must contain a title
            // But the body is optional
          },
          {
            title: 'Do you like the app so far?',
            body: 'Your feedback can make us better', // Unlike the sendNotification task, 
                                                      // the notification body can only be set through here
          },
          {
            title: 'Your opinion is very valuable',
            tapAction: { // (Optional) Including a tap action inside one of the options will override the default one (see below)
              type: TapActionType.ASK_FEEDBACK,
              id: 'special-feedback',
            },
          },
        ],
        defaultTapAction: { // (Optional) Common tap action for all the notification options that don't declare one
              type: TapActionType.ASK_FEEDBACK,
              id: 'regular-feedback',
         },
      })
    );
    
    on('notificationTapped', run('writeRecords'));
    on('notificationCleared', run('writeRecords'));

    Note: To use the writeRecords task, the persistence package must be installed and configured. See persistence package docs.

    Events

    Name Payload Description
    notificationTapped NotificationTapRecord Emitted once a notification has been tapped by the user via the system's tray. This event is only emitted if a notification tap callback has been set up
    notificationDiscarded NotificationDiscardRecord Emitted once a notification has been discarded by the user via the system's tray. This event is only emitted if a notification discard callback has been set up

    Records

    This plugin includes records which can be classified into two categories: user reactions and user interactions.

    User reactions

    User reactions include the NotificationTapRecord and the NotificationDiscardRecord.

    NotificationTapRecord

    Property Type Description
    id string Record's unique id
    type string Always notification-tap
    change Change Always none. Notification tap's starts and ends cannot be detected
    timestamp Date The local time when the notification was tapped
    notificationId number The id of the notification that has been tapped
    tapAction TapAction The tap action of the notification that has been tapped

    NotificationDiscardRecord

    Property Type Description
    id string Record's unique id
    type string Always notification-discard
    change Change Always none. Notification discard's starts and ends cannot be detected
    timestamp Date The local time when the notification was discarded
    notificationId number The id of the notification that has been discarded
    tapAction TapAction The tap action of the notification that has been discarded
    User interactions

    User interactions include the UserReadContent, QuestionnaireAnswers, UserFeedback and UserConfirmation records.

    UserReadContent

    This record is meant to be manually created (and optionally emitted, using awarns.emit()), after users close a content shown when handling an OPEN_CONTENT tap action.

    Property Type Description
    id string Record's unique id
    type string Always user-content-read
    change Change Always none. This record is meant to be used after the user finishes seeing a content. The start is reflected by the NotificationTapRecord
    timestamp Date The local time when the content was closed
    contentId string The id of the content seen by the user
    completelyRead boolean Allows to indicate if the user has seen the content to its full extension. Defaults to false
    notificationId number (Optional) The id of the notification that lead to this content being displayed

    QuestionnaireAnswers

    This record is meant to be manually created (and optionally emitted, using awarns.emit()), after users submit a set of questions delivered when handling a DELIVER_QUESTIONS tap action.

    Property Type Description
    id string Record's unique id
    type string Always questionnaire-answers
    change Change Always none. This record is meant to be used after the user finishes answering the delivered questions. The start is reflected by the NotificationTapRecord
    timestamp Date The local time when the questions were answered
    questionnaireId string The id of the questionnaire answered by the user
    answers Array<QuestionnaireAnswer Includes each of the user's answers to the questions that have been delivered. The table bellow describes each one of the properties of the QuestionnaireAnswer interface
    notificationId number (Optional) The id of the notification that lead to this questionnaire being delivered
    QuestionnaireAnswer
    Property Type Description
    title string The title of the question
    answer number | string | boolean The answer provided by the user
    millisecondsToAnswer number (Optional) The amount of milliseconds that took the user to answer the question

    UserFeedback

    This record is meant to be manually created (and optionally emitted, using awarns.emit()), after users submit some feedback they've been asked for when handling an ASK_FEEDBACK tap action.

    Property Type Description
    id string Record's unique id
    type string Always user-feedback
    change Change Always none. This record is meant to be used after the user submits feedback. The start is reflected by the NotificationTapRecord
    timestamp Date The local time when the feedback was submitted
    feedbackId string The id of the feedback form submitted by the user
    question string The matter the user has been asked for
    feedback string The answer submitted by the user
    notificationId number (Optional) The id of the notification that lead to this feedback being asked

    UserConfirmation

    This record is meant to be manually created (and optionally emitted, using awarns.emit()), after users confirm or reject a statement presented when handling an ASK_CONFIRMATION tap action.

    Property Type Description
    id string Record's unique id
    type string Always user-confirmation
    change Change Always none. This record is meant to be used after the user confirms or rejects a statement. The start is reflected by the NotificationTapRecord
    timestamp Date The local time when the statement was confirmed or rejected
    confirmationId string The id of the confirmation form answered by the user
    question string The confirmation the user has been asked for
    confirmed boolean Indicates if the user has confirmed the statement or not
    notificationId number (Optional) The id of the notification that lead to this confirmation being requested

    License

    Apache License Version 2.0

    Install

    npm i @awarns/notifications

    DownloadsWeekly Downloads

    10

    Version

    1.0.0

    License

    Apache-2.0

    Unpacked Size

    68.7 kB

    Total Files

    68

    Last publish

    Collaborators

    • matey
    • albertogonper