JUCE  v5.4.1-191-g0ab5e696f
JUCE API
Looking for a senior C++ dev?
I'm looking for work. Hire me!
juce::PushNotifications Class Reference

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

#include <juce_PushNotifications.h>

Inheritance diagram for juce::PushNotifications:
Collaboration 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 addListener (Listener *l)
 
bool areNotificationsEnabled () const
 Checks whether notifications are enabled for given application. More...
 
void getDeliveredNotifications () const
 Sends a request for a list of notifications delivered. More...
 
String getDeviceToken () const
 Retrieves current device token. More...
 
void getPendingLocalNotifications () const
 iOS only: sends an asynchronous request to retrieve a list of notifications that were scheduled and not yet delivered. More...
 
void removeAllDeliveredNotifications ()
 Removes all notifications that were delivered. More...
 
void removeAllPendingLocalNotifications ()
 Unschedules all pending local notifications. More...
 
void removeDeliveredNotification (const String &identifier)
 Removes a previously delivered notification. More...
 
void removeListener (Listener *l)
 
void removePendingLocalNotification (const String &identifier)
 Unschedules a pending local notification with a given identifier. More...
 
void requestPermissionsWithSettings (const Settings &settings)
 Initialises push notifications on current device with the settings provided. More...
 
void requestSettingsUsed ()
 Sends an asynchronous request to retrieve current settings that are currently in use. More...
 
void sendLocalNotification (const Notification &notification)
 On iOS as well as on Android, sends a local notification. More...
 
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. More...
 
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. More...
 
void subscribeToTopic (const String &topic)
 Android only: allows to subscribe to messages from a specific topic. More...
 
void unsubscribeFromTopic (const String &topic)
 Android only: allows to remove a topic subscription that was previously added with subscribeToTopic(). More...
 

Private Member Functions

 PushNotifications ()
 
 ~PushNotifications ()
 

Static Private Member Functions

static void deleteAll ()
 Deletes all extant objects. More...
 

Private Attributes

ListenerList< PushNotifications::Listenerlisteners
 

Friends

void juce_firebaseDeviceNotificationsTokenRefreshed (void *)
 
void juce_firebaseRemoteMessagesDeleted ()
 
void juce_firebaseRemoteMessageSendError (void *, void *)
 
void juce_firebaseRemoteMessageSent (void *)
 
void juce_firebaseRemoteNotificationReceived (void *)
 
bool juce_handleNotificationIntent (void *)
 

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.

{GUI}

Constructor & Destructor Documentation

◆ PushNotifications()

juce::PushNotifications::PushNotifications ( )
private

◆ ~PushNotifications()

juce::PushNotifications::~PushNotifications ( )
private

Member Function Documentation

◆ addListener()

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

◆ 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.

◆ deleteAll()

static void juce::DeletedAtShutdown::deleteAll ( )
staticinherited

Deletes all extant objects.

This shouldn't be used by applications, as it's called automatically in the shutdown code of the JUCEApplicationBase class.

◆ 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.

◆ 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.

◆ 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.

◆ removeAllDeliveredNotifications()

void juce::PushNotifications::removeAllDeliveredNotifications ( )

Removes all notifications that were delivered.

◆ removeAllPendingLocalNotifications()

void juce::PushNotifications::removeAllPendingLocalNotifications ( )

Unschedules all pending local notifications.

iOS only.

◆ 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.

◆ removeListener()

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

◆ removePendingLocalNotification()

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

Unschedules a pending local notification with a given identifier.

Available from iOS 10.

◆ 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.

◆ 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().

◆ 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.

◆ 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
serverSenderIdRepresents the sender. Consult your Firebase project settings to retrieve the sender id.
collapseKeyRemote 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.
messageIdA unique message ID. Used in error callbacks and debugging.
messageTypeMessage type.
timeToLiveTTL 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.
additionalDataCollection of key-value pairs to be used as an additional data for the message.

◆ 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.

◆ 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.

◆ unsubscribeFromTopic()

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

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

Friends And Related Function Documentation

◆ juce_firebaseDeviceNotificationsTokenRefreshed

void juce_firebaseDeviceNotificationsTokenRefreshed ( void *  )
friend

◆ juce_firebaseRemoteMessagesDeleted

void juce_firebaseRemoteMessagesDeleted ( )
friend

◆ juce_firebaseRemoteMessageSendError

void juce_firebaseRemoteMessageSendError ( void *  ,
void *   
)
friend

◆ juce_firebaseRemoteMessageSent

void juce_firebaseRemoteMessageSent ( void *  )
friend

◆ juce_firebaseRemoteNotificationReceived

void juce_firebaseRemoteNotificationReceived ( void *  )
friend

◆ juce_handleNotificationIntent

bool juce_handleNotificationIntent ( void *  )
friend

Member Data Documentation

◆ listeners

ListenerList<PushNotifications::Listener> juce::PushNotifications::listeners
private

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