@awarns/notifications v1.0.2

@awarns/notifications

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:

API

notificationsManager

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

notifications

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

Notification

TapAction

TapActionType

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.

• notificationTapped
• notificationDiscarded

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.

• notificationTapped
• notificationDiscarded

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

Records

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

User reactions include the NotificationTapRecord and the NotificationDiscardRecord.

NotificationTapRecord

NotificationDiscardRecord

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.

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.

QuestionnaireAnswer

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.

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.

License

Apache License Version 2.0