@hilma/push-notifications v1.2.0

@hilma/push-notifications

A Push-Notifications Plugin, meant to work with @capacitor/push-notifications and @capacitor-community/fcm. added optionality to override silent mode, set the push-volume from the client-side and more.

!!!Implemented for Android only!!! - for IOS please refer to critical-alerts

Install

npm install @hilma/push-notifications
npx cap sync

API

• Manifest Config
• Global Settings (Config)
• Project Variables
• Ringtone Files
• setSettings(...)
• setSetting(...)
• getSettings()
• getNotifications()
• clearStoredNotifications()
• Interfaces
• Type Aliases
• Server Api + Example

Declare the permission - Manifest config

For the plugin to work, add this section into your AndroidManifest.xml file above the application tag Also - required! -> Add the notification-icon to your manifest meta-data (--Will crash the app if not present)

<manifest ...>
    <uses-permission android:name="android.permission.POST_NOTIFICATIONS"/> <!--  This will allow the plugin to launch a custom notification to the user -->
    <uses-permission android:name="android.permission.ACCESS_NOTIFICATION_POLICY" /> <!--  This will allow the plugin to listen for incoming data messages -->
    <uses-permission android:name="android.permission.FOREGROUND_SERVICE" /> <!--  This will allow the plugin to listen to incoming messages even if the app is killed -->
    <uses-permission android:name="android.permission.VIBRATE" />   <!-- optional - only if your notifications require vibrations -->
    <application ...>
        <meta-data
            android:name="com.google.firebase.messaging.default_notification_icon"
            android:resource="@path/to/icon/here" /> <!-- Adding the desired notification icon -->
        ...
    </application>
</manifest>

Project Variables

This plugin will use the following project variables (defined in your app's variables.gradle file):

• firebaseMessagingVersion version of com.google.firebase:firebase-messaging (default: 23.3.1)
• gsonVersion version of com.google.code.gson:gson (default: 2.8.9)
• firebaseMessagingDirectboot version of com.google.firebase:firebase-messaging-directboot (default: 20.2.0)
• firebaseBomVersion version of com.google.firebase:firebase-bom (default: 31.0.0)

Global Settings

You can configure the way the plugin behaves initialy in capacitor.config.json or capacitor.config.ts

Examples

in capacitor.config.json

{
  "plugins": {
    "HilmaPushNotifications": {
      "defaultRingtoneFileName": "MyCustomRingtone",
      "defaultVolume": 100,
      "defaultOverrideSilentEnabled": true,
      "lights": ["FFFFF", "300", "100"],
      "vibrationPattern": ["1000", "500", "1000", "500"]
    }
  }
}

in capacitor.config.ts

/// <reference types="@hilma/push-notifications" />

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  plugins: {
    HilmaPushNotifications: {
      defaultRingtoneFileName: 'MyCustomRingtone',
      defaultVolume: 100,
      defaultOverrideSilentEnabled: true,
      lights: ['FFFFF', '300', '100'],
      vibrationPattern: ['1000', '500', '1000', '500'],
    },
  },
};

export default config;

Ringtone files

You should save your ringtone files in android/app/src/main/res/raw Your ringtone files must be of .mp3 file type

setSettings(...)

setSettings(options: AndroidSettings) => Promise<void>

Sets the Android settings for push notifications.

setSetting(...)

setSetting<T extends keyof AndroidSettings>(options: { key: T; value: AndroidSettings[T]; }) => Promise<void>

Sets a specific Android setting for push notifications.

getSettings()

getSettings() => Promise<AndroidSettings>

Gets the current Android settings for push notifications.

Returns: Promise<AndroidSettings>

getNotifications()

getNotifications<T extends Record<string, string> = Record<string, string>>() => Promise<{ notifications: PushMessages<T>[]; }>

Retrieves all the stored push notifications

Returns: Promise<{ notifications: PushMessages<T>[]; }>

clearStoredNotifications()

clearStoredNotifications() => Promise<void>

Clears all stored notifications

Interfaces

AndroidSettings

PushMessages

Interface representing push messages received.

Type Aliases

Record

Construct a type with a set of properties K of type T

{

}

Server API

This plugin works with what's called Data messages That means that the notification sent to the client is a silent notification, not visible by default to the client and automaticaly sent to the app itself. The HilmaPushNotificationsPlugin intercepts this data message and fires a notification localy based on the data recieved from firebase.

Example: using firebase-admin

import * as admin from 'firebase-admin';

async function sendMessageToToken(token: string) {
  return await admin.messaging().send({
    token,
    data: {
      should_override_silent: 'yes', //inorder to override silent mode
      title: 'Your title',
      text: 'your Text',
      notificationId: 100, // optional
      otherRelevantData: 'What ever data you need',
    },
    android: {
      priority: 'high',
      //note that we do not add the `notification` field inorder to keep this a data message
    },
    apns: {
      //! Sending a normal notification for ios, as the plugin is for android only !
      payload: {
        aps: {
          alert: { title: 'Your title', subtitle: 'Your text' },
          badge: 1,
          sound: {
            name: 'your-ringtone.caf',
            critical: true, //inorder to send this message as a critical alert
            volume: 1, //set volume to the maximum
          },
        },
      },
    },
  });
}