Singleton class responsible for push notifications functionality. More...

#include "juce_PushNotifications.h"

Inheritance diagram for juce::PushNotifications:

Classes
struct	Channel
	Android API level 26 or higher only: Represents notification channel through which notifications will be sent. More...

struct	ChannelGroup
	Android API level 26 or higher only: represents a channel group. More...

struct	Listener
	Register a listener (ideally on application startup) to receive information about notifications received and any callbacks to async functions called. More...

struct	Notification
	Represents a notification that can be sent or received. More...

struct	Settings
	Describes settings we want to use for current device. More...

Public Member Functions
void	requestPermissionsWithSettings (const Settings &settings)
	Initialises push notifications on current device with the settings provided.

void	requestSettingsUsed ()
	Sends an asynchronous request to retrieve current settings that are currently in use.

void	setupChannels (const Array< ChannelGroup > &groups, const Array< Channel > &channels)
	Android API level 26 or higher only: configures notification channel groups and channels to be used in the app.

void	getPendingLocalNotifications () const
	iOS only: sends an asynchronous request to retrieve a list of notifications that were scheduled and not yet delivered.

void	removePendingLocalNotification (const String &identifier)
	Unschedules a pending local notification with a given identifier.

void	removeAllPendingLocalNotifications ()
	Unschedules all pending local notifications.

bool	areNotificationsEnabled () const
	Checks whether notifications are enabled for given application.

void	sendLocalNotification (const Notification &notification)
	On iOS as well as on Android, sends a local notification.

void	getDeliveredNotifications () const
	Sends a request for a list of notifications delivered.

void	removeDeliveredNotification (const String &identifier)
	Removes a previously delivered notification.

void	removeAllDeliveredNotifications ()
	Removes all notifications that were delivered.

String	getDeviceToken () const
	Retrieves current device token.

void	subscribeToTopic (const String &topic)
	Android only: allows to subscribe to messages from a specific topic.

void	unsubscribeFromTopic (const String &topic)
	Android only: allows to remove a topic subscription that was previously added with subscribeToTopic().

void	sendUpstreamMessage (const String &serverSenderId, const String &collapseKey, const String &messageId, const String &messageType, int timeToLive, const StringPairArray &additionalData)
	Android only: sends an upstream message to your app server.

void	addListener (Listener *l)

void	removeListener (Listener *l)

Detailed Description

Singleton class responsible for push notifications functionality.

Both remote and local notifications are supported. To get information about notifications, register a listener on your application startup. It is best to register the listener as soon as possible, because your application can be launched from a push notification too.

To send a local notification create an instance of Notification, fill the necessary fields and call PushNotifications::sendLocalNotification(). When receiving local or remote notifications, inspect the Notification's fields for notification details. Bear in mind that some fields will not be available when receiving a remote notification.

@tags{GUI}

Definition at line 45 of file juce_PushNotifications.h.

Class Documentation

◆ juce::PushNotifications::ChannelGroup

struct juce::PushNotifications::ChannelGroup

Android API level 26 or higher only: represents a channel group.

This allows for visual grouping of corresponding channels in notification settings presented to the user. At least one channel group has to be specified before notifications can be sent.

Definition at line 481 of file juce_PushNotifications.h.

Class Members
String	identifier	Required: Unique channel group identifier.
String	name	Required: User visible name of the channel group.

◆ juce::PushNotifications::Settings

struct juce::PushNotifications::Settings

Describes settings we want to use for current device.

Note that at the moment this is only used on iOS and partially on OSX.

On OSX only allow* flags are used and they control remote notifications only. To control sound, alert and badge settings for local notifications on OSX, use Notifications settings in System Preferences.

To setup push notifications for current device, provide permissions required, as well as register categories of notifications you want to support. Each category needs to have a unique identifier and it can optionally have multiple actions. Each action also needs to have a unique identifier. The example setup may look as follows:

using Action   = PushNotifications::Settings::Action;
using Category = PushNotifications::Settings::Category;
 
Action okAction;
okAction.identifier = "okAction";
okAction.title = "OK!";
okAction.style = Action::button;
okAction.triggerInBackground = true;
 
Action cancelAction;
cancelAction.identifier = "cancelAction";
cancelAction.title = "Cancel";
cancelAction.style = Action::button;
cancelAction.triggerInBackground = true;
cancelAction.destructive = true;
 
Action textAction;
textAction.identifier = "textAction";
textAction.title = "Enter text";
textAction.style = Action::text;
textAction.triggerInBackground = true;
textAction.destructive = false;
textAction.textInputButtonText = "Ok";
textAction.textInputPlaceholder = "Enter text...";
 
Category okCategory;
okCategory.identifier = "okCategory";
okCategory.actions = { okAction };
 
Category okCancelCategory;
okCancelCategory.identifier = "okCancelCategory";
okCancelCategory.actions = { okAction, cancelAction };
 
Category textCategory;
textCategory.identifier = "textCategory";
textCategory.actions = { textAction };
textCategory.sendDismissAction = true;
 
PushNotifications::Settings settings;
settings.allowAlert = true;
settings.allowBadge = true;
settings.allowSound = true;
settings.categories = { okCategory, okCancelCategory, textCategory };

Definition at line 387 of file juce_PushNotifications.h.

Class Members
typedef Action	Action

Class Members
bool	allowAlert	whether the app should present an alert upon notification
bool	allowBadge	whether the app may badge its icon upon notification
bool	allowSound	whether the app should play a sound upon notification
Array< Category >	categories	list of categories the app wants to support

Member Function Documentation

◆ addListener()

void juce::PushNotifications::addListener ( Listener * l )

Definition at line 86 of file juce_PushNotifications.cpp.

◆ areNotificationsEnabled()

bool juce::PushNotifications::areNotificationsEnabled ( ) const

Checks whether notifications are enabled for given application.

On iOS and OSX this will always return true, use requestSettingsUsed() instead.

Definition at line 107 of file juce_PushNotifications.cpp.

◆ getDeliveredNotifications()

void juce::PushNotifications::getDeliveredNotifications ( ) const

Sends a request for a list of notifications delivered.

Such notifications are visible in the notification area on the device and they are still waiting for user action/response. When the request is finished Listener::deliveredNotificationsListReceived() will be called.

On iOS, iOS version 10 or higher is required. On Android, API level 18 or higher is required. For unsupported platforms, Listener::deliveredNotificationsListReceived() will return an empty array.

Definition at line 116 of file juce_PushNotifications.cpp.

◆ getDeviceToken()

String juce::PushNotifications::getDeviceToken ( ) const

Retrieves current device token.

Note, it is not a good idea to cache this token because it may change in the meantime. Always call this method to get the current token value.

Definition at line 130 of file juce_PushNotifications.cpp.

◆ getPendingLocalNotifications()

void juce::PushNotifications::getPendingLocalNotifications ( ) const

iOS only: sends an asynchronous request to retrieve a list of notifications that were scheduled and not yet delivered.

When the list is retrieved, Listener::pendingLocalNotificationsListReceived() will be called.

Definition at line 146 of file juce_PushNotifications.cpp.

◆ removeAllDeliveredNotifications()

void juce::PushNotifications::removeAllDeliveredNotifications ( )

Removes all notifications that were delivered.

Definition at line 123 of file juce_PushNotifications.cpp.

◆ removeAllPendingLocalNotifications()

void juce::PushNotifications::removeAllPendingLocalNotifications ( )

Unschedules all pending local notifications.

iOS only.

Definition at line 153 of file juce_PushNotifications.cpp.

◆ removeDeliveredNotification()

void juce::PushNotifications::removeDeliveredNotification ( const String & identifier )

Removes a previously delivered notification.

This can be useful for instance when the information in the notification becomes obsolete.

Definition at line 182 of file juce_PushNotifications.cpp.

◆ removeListener()

void juce::PushNotifications::removeListener ( Listener * l )

Definition at line 87 of file juce_PushNotifications.cpp.

◆ removePendingLocalNotification()

void juce::PushNotifications::removePendingLocalNotification ( const String & identifier )

Unschedules a pending local notification with a given identifier.

Available from iOS 10.

Definition at line 189 of file juce_PushNotifications.cpp.

◆ requestPermissionsWithSettings()

void juce::PushNotifications::requestPermissionsWithSettings ( const Settings & settings )

Initialises push notifications on current device with the settings provided.

Call this on your application startup and on iOS the first time the application starts, a user will be presented with a permission request dialog to give push notifications permission. Once a user responds, Listener::notificationSettingsReceived() will be called so that you can check what permissions where actually granted. The listener callback will be called on each subsequent startup too (provided you called requestPermissionsWithSettings() on previous application run). This way you can check what are current push notifications permissions.

Note that settings are currently only used on iOS. When calling on other platforms, Settings with no categories and all allow* flags set to true will be received in Listener::notificationSettingsReceived().

You can also call requestSettingsUsed() to explicitly ask for current settings.

Definition at line 89 of file juce_PushNotifications.cpp.

◆ requestSettingsUsed()

void juce::PushNotifications::requestSettingsUsed ( )

Sends an asynchronous request to retrieve current settings that are currently in use.

These can be exactly the same as used in requestPermissionsWithSettings(), but depending on user's subsequent changes in OS settings, the actual current settings may be different (e.g. user might have later decided to disable sounds).

Note that settings are currently only used on iOS and partially on OSX.

On OSX, only allow* flags are used and they refer to remote notifications only. For local notifications, refer to System Preferences.

When calling this function on other platforms, Settings with no categories and all allow* flags set to true will be received in Listener::notificationSettingsReceived().

Definition at line 98 of file juce_PushNotifications.cpp.

◆ sendLocalNotification()

void juce::PushNotifications::sendLocalNotification ( const Notification & notification )

On iOS as well as on Android, sends a local notification.

On Android and iOS 10 or above, this will refresh an existing notification if the same identifier is used as in a notification that was already sent and not yet responded by a user.

Definition at line 175 of file juce_PushNotifications.cpp.

◆ sendUpstreamMessage()

void juce::PushNotifications::sendUpstreamMessage	(	const String &	serverSenderId,
		const String &	collapseKey,
		const String &	messageId,
		const String &	messageType,
		int	timeToLive,
		const StringPairArray &	additionalData
	)

Android only: sends an upstream message to your app server.

The server must implement XMPP Connection Server protocol (refer to Firebase documentation).

Parameters

serverSenderId	Represents the sender. Consult your Firebase project settings to retrieve the sender id.
collapseKey	Remote messages with the same collapse key that were not yet delivered will be collapsed into one, with the newest message replacing all the previous ones. Note that there may be a limit of maximum collapse keys used at the same time and beyond the limit (refer to Firebase documentation) it is not guaranteed which keys will be in use by the server.
messageId	A unique message ID. Used in error callbacks and debugging.
messageType	Message type.
timeToLive	TTL in seconds. If 0, the message sending will be attempted immediately and it will be dropped if the device is not connected. Otherwise, the message will be queued for the period specified.
additionalData	Collection of key-value pairs to be used as an additional data for the message.

Definition at line 196 of file juce_PushNotifications.cpp.

◆ setupChannels()

void juce::PushNotifications::setupChannels	(	const Array< ChannelGroup > &	groups,
		const Array< Channel > &	channels
	)

Android API level 26 or higher only: configures notification channel groups and channels to be used in the app.

These have to be setup before notifications can be sent on Android API level 26 or higher.

Definition at line 139 of file juce_PushNotifications.cpp.

◆ subscribeToTopic()

void juce::PushNotifications::subscribeToTopic ( const String & topic )

Android only: allows to subscribe to messages from a specific topic.

So you could for instance subscribe this device to all "sports" topic messages to receive any remote notifications that have "sports" topic set. Refer to Firebase documentation for how to send topic messages.

Definition at line 160 of file juce_PushNotifications.cpp.

◆ unsubscribeFromTopic()

void juce::PushNotifications::unsubscribeFromTopic ( const String & topic )

Android only: allows to remove a topic subscription that was previously added with subscribeToTopic().

Definition at line 167 of file juce_PushNotifications.cpp.

The documentation for this class was generated from the following files:

juce_gui_extra/misc/juce_PushNotifications.h
juce_gui_extra/misc/juce_PushNotifications.cpp

Classes

Public Member Functions