Remote Notifications
In this page you'll learn how notifications are handled in your app and what all the options at your disposal to create a great messaging experience for your users.
Handling opens from Notification Manager
Since Android 12, apps are forced to handle notification opens in an activity. The Notificare Android SDK will launch an intent re.notifica.intent.action.RemoteMessageOpened
whenever one is clicked. The plugin already takes care of this for you, but your (main) activity will have to declare this intent filter.
<intent-filter>
<action android:name="re.notifica.intent.action.RemoteMessageOpened" />
<category android:name="android.intent.category.DEFAULT" />
</intent-filter>
Receiving Notifications
In your App.js, you'll need to implement the following event listener in order to receive a notification whenever it arrives and the app is being used:
Notificare.on('remoteNotificationReceivedInForeground', function(data) {
//Here you probably don't want to interrupt the user and simply show that a notification has arrive with an in-app badge
});
Notificare.on('remoteNotificationReceivedInForeground', (data) => {
//Here you probably don't want to interrupt the user and simply show that a notification has arrive with an in-app badge
});
The best approach when the app is being used and a notification arrives, is to not interrupt the user, you can save this information and display some UI element that warns the user without interrupting whatever the user was doing.
But in most cases, notifications will arrive when the app is not being used. Users will click on it from the notification center or lock screen and you will want to show those immediately to the user. In those cases the following event will be triggered:
Notificare.on('remoteNotificationReceivedInBackground', function(data) {
});
Notificare.on('remoteNotificationReceivedInBackground', (data) => {
});
Whenever this delegate is triggered you will need to handle it accordingly by presenting the notification. This is achieved by using the following method:
Notificare.on('remoteNotificationReceivedInBackground', function(data) {
Notificare.presentNotification(data);
});
Notificare.on('remoteNotificationReceivedInBackground', async (data) => {
await Notificare.presentNotification(data);
});
System Notifications
In Notificare you can send silent notifications that will wake up your app and can be used to download new data. These are called System Notifications and will not be added to the device's lock screen or notification center nor they will be added to the inbox (if implemented).
In Android, these are handled by the Receiver in the native part of your app. To handle these notifications, please refer to the Android SDK docs.
Notifications from Unknown Sources
In some apps it possible you're also using other providers to send remote notifications, when that is the case Notificare will recognize an unknown notification and ignore it. If you want to allow non-Notificare messages, these should be handled by a custom IntentReceiver in the native part of your app and you will have to provide your own mechanism to have them end up in your Cordova code.
Deep Links
In modern apps, this is a great way of creating interactions between notifications and your own app content, allowing you to send messages that can eventually drive the user to open content hidden deeper in your app.
To prepare your app to handle deep links is not complicated and will allow you to handle not only Deep Link notification types, but also any link executed from a web page. In order to indicate that your MainActivity should handle a custom URL Scheme you will have to declare the following in your AndroidManifest.xml file:
<activity
android:name=".MainActivity"
android:label="@string/app_name"
android:launchMode="singleTop"
android:configChanges="keyboard|keyboardHidden|orientation|screenSize">
<intent-filter>
<action android:name="android.intent.action.MAIN" />
<category android:name="android.intent.category.LAUNCHER" />
</intent-filter>
<intent-filter>
<action android:name="re.notifica.intent.action.NotificationOpened" />
<category android:name="android.intent.category.DEFAULT" />
</intent-filter>
<intent-filter android:label="my_deep_link">
<action android:name="android.intent.action.VIEW" />
<category android:name="android.intent.category.DEFAULT" />
<category android:name="android.intent.category.BROWSABLE" />
<data android:scheme="@string/app_url_scheme"/>
</intent-filter>
</activity>
The example above assumes you've added the value of your URL Scheme in res/values/strings.xml as follows:
<?xml version="1.0" encoding="utf-8"?>
<resources>
...more
<string name="app_url_scheme">your.deep.link</string>
...more
</resources>
To handle a notification of type Deep Link or when a user clicks in an action of type Open App you should implement the following in your javascript:
Notificare.on('urlOpened', function(data) {
//Handle URL
});
Notificare.on('urlOpened', (data) => {
//Handle URL
});
<queries>
<intent>
<action android:name="android.intent.action.VIEW" />
<category android:name="android.intent.category.BROWSABLE" />
<data android:scheme="https" />
</intent>
<intent>
<action android:name="android.intent.action.VIEW" />
<category android:name="android.intent.category.BROWSABLE" />
<data android:scheme="http" />
</intent>
</queries>
There is yet another situation where you will also want to handle deep links and that is when users click in a link in a HTML or Web Page notification. If that link should open a view in your app you will want to intercept those clicks and handle it the same way you handle deep links.
First make sure you declare those URL Scheme in res/values/url_schemes.xml:
<?xml version="1.0" encoding="utf-8"?>
<resources>
<string-array name="url_schemes">
<item>your.deep.link</item>
</string-array>
</resources>
Our library will then intercept all the links using those URL Schemes and trigger the following event:
Notificare.on('urlClickedInNotification', function(data) {
//Handle URL
});
Notificare.on('urlClickedInNotification', (data) => {
//Handle URL
});
Inbox
With our library it's extremely easy to implement an in-app inbox. Implementing an inbox increases considerably the engagement rates of your notifications simply because messages will always be available inside your app. To activate the inbox functionality, please follow the instructions described here.
After activating this functionality, implement the following event listener in your App.js which will be triggered whenever the inbox initializes or reloads its data:
Notificare.on('inboxLoaded', function(inboxItems) {
//Update your list of inbox items
});
Notificare.on('inboxLoaded', (inboxItems) => {
//Update your list of inbox items
});
In Android, this event will be called every time anything changes to your inbox, be it items added or removed or their read-state changed. You can still explicitly fetch the inbox, but if you are using a listener to the inboxLoaded event, this is not needed:
Notificare.fetchInbox(function(inboxItems) {
//Handle the list of inbox items
}, function(e) {
//Handle error
});
const inboxItems = await Notificare.fetchInbox();
To open a message from the list of messages in the inbox, please use the following method:
//Use an object from the fetchInbox() result
var inboxItem = inboxItems[0];
Notificare.presentInboxItem(inboxItem);
//Use an object from the fetchInbox() result
const inboxItem = inboxItems[0];
await Notificare.presentInboxItem(inboxItem);
At anytime you can also delete a notification from the inbox:
//Use an object from the fetchInbox() result
var inboxItem = inboxItems[0];
Notificare.removeFromInbox(inboxItem, function(result) {
//Handle success
}, function(e) {
//Handle error
});
//Use an object from the fetchInbox() result
const inboxItem = inboxItems[0];
await Notificare.removeFromInbox(inboxItem);
Additionally you can also mark a message as read by invoking the following method:
//Use an object from the fetchInbox() result
let inboxItem = inboxItems[0];
Notificare.markAsRead(inboxItem, function(result) {
//Handle success
}, function(e) {
//Handle error
});
//Use an object from the fetchInbox() result
const inboxItem = inboxItems[0];
await Notificare.markAsRead(inboxItem);
Additionally, in 2.4 and up, you can also mark all messages as read by invoking the following method:
Notificare.markAllAsRead(function(result) {
//Handle success
}, function(e) {
//Handle error
});
await Notificare.markAllAsRead();
Finally to remove all the items in the inbox you would do the following:
Notificare.clearInbox(function(result) {
//Handle success
}, function(e) {
//Handle error
});
await Notificare.clearInbox();
If you want to keep track of the number of unread messages in the inbox, you can implement the following event listener in your App.js. This will be triggered whenever there's changes to the inbox items unread count and can help you manage your UI:
Notificare.on('badgeUpdated', function(badge) {
//Use this to display a badge in your app
});
Notificare.on('badgeUpdated', (badge) => {
//Use this to display a badge in your app
});