PushNotifications::Notification Struct Reference

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

#include <juce_PushNotifications.h>

Classes
struct	Action
	Represents an action on a notification that can be presented as a button or a text input. More...
struct	LedBlinkPattern
	Allows to control the time the device's led is on and off. More...
struct	Progress
	Used to represent a progress of some operation. More...

Public Member Functions
	Notification ()=default
	Notification (const Notification &other)
bool	isValid () const noexcept
	Checks whether a given notification is correctly configured for a given OS.

Public Attributes
Common fields
String	identifier
	Required: unique id that can be used to later dismiss the notification (on iOS available from version 10).
String	title
	Required: the title of the notification, usually displayed in the first row.
String	body
	Required: the content of the notification, usually displayed in the second row.
String	subtitle
	Optional: additional text, that may be displayed e.g.
String	groupId
	Optional: allows the OS to visually group, collapse, and expand a set of notifications, note that OS may automatically group notifications if no groupId is specified.
int	badgeNumber = 0
	Optional: on platforms that support it, can set a number this notification represents.
URL	soundToPlay
	Optional: empty when the notification should be silent.
var	properties
	Optional: collection of additional properties that may be passed as a dictionary.
iOS only fields
String	category
	Required: determines set of actions that will appear (as per setup done in requestPermissionsWithSettings()).
double	triggerIntervalSec = 0.
	Optional: specifies number of seconds before the notification should trigger.
bool	repeat = false
	Optional: allows the notification to continuously retrigger after triggerIntervalSec seconds.

Android only fields
enum	Type {   unspecified , alarm , call , email ,   error , event , message , taskProgress ,   promo , recommendation , reminder , service ,   social , status , system , transport }
	Metadata that can be used by the OS to better handle the notification, depending on its priority. More...
enum	Priority {   veryLow = -2 , low = -1 , medium = 0 , high = 1 ,   veryHigh = 2 }
	Metadata used as a hint to the OS about the priority of the notification. More...
enum	LockScreenAppearance { dontShow = -1 , showPartially = 0 , showCompletely = 1 }
	Describes how to show the notification when the screen is locked. More...
enum	TimestampVisibility { off , normal , chronometer , countDownChronometer }
	Controls timestamp visibility and format. More...
enum	BadgeIconType { none , small , large }
	Controls badge icon type to use if a notification is shown as a badge. More...
enum	GroupAlertBehaviour { alertAll , AlertSummary , AlertChildren }
	Controls sound and vibration behaviour for group notifications. More...
String	icon
	Required: name of an icon file (without an extension) to be used for this notification.
String	channelId
	Required for Android API level 26 or above: specifies notification channel id.
Image	largeIcon
	Optional: an additional large icon displayed in the notification content view.
String	tickerText
	Optional: ticker text used for accessibility services.
Array< Action >	actions
	Optional: actions associated with the notification.
Progress	progress
	Optional: set to default (0, 0, false), to disable progress display.
String	person
	Optional: additional metadata used as a hint to OS that a notification is related to a specific person.
Type	type = unspecified
	Optional.
Priority	priority = medium
	Optional.
LockScreenAppearance	lockScreenAppearance = showPartially
	Optional.
std::unique_ptr< Notification >	publicVersion
	Optional: if you set lockScreenAppearance to showPartially, then you can provide "public version" of your notification that will be displayed on the lock screen.
String	groupSortKey
	Optional: Used to order notifications within the same group.
bool	groupSummary = false
	Optional: if true, then this notification will be a group summary of the group set with groupId.
Colour	accentColour
	Optional: sets accent colour.
Colour	ledColour
	Optional: Sets the led colour.
LedBlinkPattern	ledBlinkPattern
	Optional.
Array< int >	vibrationPattern
	Optional: sets the vibration pattern in milliseconds.
bool	shouldAutoCancel = true
	Optional: If true, the notification will be automatically cancelled when a user clicks it in the panel.
bool	localOnly = true
	Optional: whether or not the notification should bridge to other devices.
bool	ongoing = false
	Optional: If true, then it cannot be dismissed by the user and it must be dismissed manually.
bool	alertOnlyOnce = false
	Optional: Set this flag if you would only like the sound, vibrate and ticker to be played if the notification is not already showing.
TimestampVisibility	timestampVisibility = normal
	Optional.
BadgeIconType	badgeIconType = large
GroupAlertBehaviour	groupAlertBehaviour = alertAll
int	timeoutAfterMs = 0
	specifies a duration in milliseconds, after which the notification should be cancelled, if it is not already cancelled.

Detailed Description

Represents a notification that can be sent or received.

Member Enumeration Documentation

Type

enum PushNotifications::Notification::Type

Metadata that can be used by the OS to better handle the notification, depending on its priority.

Enumerator
unspecified	Category not set.
alarm	Alarm or timer.
call	Incoming voice/video call or similar.
email	Async message like email.
error	Error in background operation or authentication status.
event	Calendar event.
message	Incoming message (sms, instant message etc.).
taskProgress	Progress for a long-running background operation.
promo	Promotion or advertisement.
recommendation	Specific, single thing related recommendation.
reminder	User-scheduled reminder.
service	Running background service.
social	Social network or sharing update.
status	Ongoing information about device or contextual status.
system	System or device status update.
transport	Media transport control for playback.

Priority

enum PushNotifications::Notification::Priority

Metadata used as a hint to the OS about the priority of the notification.

Enumerator
veryLow
low
medium
high
veryHigh

LockScreenAppearance

enum PushNotifications::Notification::LockScreenAppearance

Describes how to show the notification when the screen is locked.

Available from Android API 21 or above.

Enumerator
dontShow	The notification is not allowed on the lock screen.
showPartially	Only some information is allowed on the lock screen.
showCompletely	The entire notification is allowed on the lock screen.

TimestampVisibility

enum PushNotifications::Notification::TimestampVisibility

Controls timestamp visibility and format.

Enumerator
off	Do not show timestamp.
normal	Show normal timestamp.
chronometer	Show chronometer as a stopwatch. Available from Android API 16 or above.
countDownChronometer	Set the chronometer to count down instead of counting up. Available from Android API 24 or above.

BadgeIconType

enum PushNotifications::Notification::BadgeIconType

Controls badge icon type to use if a notification is shown as a badge.

Available from Android API 26 or above.

Enumerator
none
small
large

GroupAlertBehaviour

enum PushNotifications::Notification::GroupAlertBehaviour

Controls sound and vibration behaviour for group notifications.

Available from Android API 26 or above.

Enumerator
alertAll	both child notifications and group notifications should produce sound and vibration.
AlertSummary	all child notifications in the group should have no sound nor vibration, even if corresponding notification channel has sounds and vibrations enabled.
AlertChildren	summary notifications in the group should have no sound nor vibration, even if corresponding notification channel has sounds and vibrations enabled.

Constructor & Destructor Documentation

Notification() [1/2]

PushNotifications::Notification::Notification ( )

default

Notification() [2/2]

PushNotifications::Notification::Notification

(

const Notification &

other

)

Member Function Documentation

isValid()

bool PushNotifications::Notification::isValid ( ) const

noexcept

Checks whether a given notification is correctly configured for a given OS.

Member Data Documentation

identifier

String PushNotifications::Notification::identifier

Required: unique id that can be used to later dismiss the notification (on iOS available from version 10).

title

String PushNotifications::Notification::title

Required: the title of the notification, usually displayed in the first row.

body

String PushNotifications::Notification::body

Required: the content of the notification, usually displayed in the second row.

subtitle

String PushNotifications::Notification::subtitle

Optional: additional text, that may be displayed e.g.

in the third row or in the header area. Note that on Android, depending on OS version, this may fight for space with other components of the notification, so use this field judiciously. On iOS available from version 10. On Android available from API 16.

groupId

String PushNotifications::Notification::groupId

Optional: allows the OS to visually group, collapse, and expand a set of notifications, note that OS may automatically group notifications if no groupId is specified.

Available on Android API 20 or above and iOS 10 or above.

badgeNumber

int PushNotifications::Notification::badgeNumber = 0

Optional: on platforms that support it, can set a number this notification represents.

soundToPlay

URL PushNotifications::Notification::soundToPlay

Optional: empty when the notification should be silent.

When the name is set to "default_os_sound", then a default sound will be used.

For a custom sound on OSX, set the URL to the name of a sound file (preferably without an extension) and place the sound file directly in bundle's "Resources" directory (you can use "Xcode Resource" tickbox in Projucer to achieve that), i.e. it cannot be in a subdirectory of "Resources" like "Resources/sound". Alternatively, if a sound file cannot be found in bundle's "Resources" directory, the OS may look for the sound in the following paths: "~/Library/Sounds", "/Library/Sounds", "/Network/Library/Sounds", "/System/Library/Sounds".

For a custom sound on iOS, set the URL to a relative path within your bundle, including file extension. For instance, if your bundle contains "sounds" folder with "my_sound.caf" file, then the URL should be "sounds/my_sound.caf".

For a custom sound on Android, set URL to the name of a raw resource file (without an extension) that was included when exporting an Android project in Projucer (see "Extra Android Raw Resources" setting).

properties

var PushNotifications::Notification::properties

Optional: collection of additional properties that may be passed as a dictionary.

category

String PushNotifications::Notification::category

Required: determines set of actions that will appear (as per setup done in requestPermissionsWithSettings()).

triggerIntervalSec

double PushNotifications::Notification::triggerIntervalSec = 0.

Optional: specifies number of seconds before the notification should trigger.

repeat

bool PushNotifications::Notification::repeat = false

Optional: allows the notification to continuously retrigger after triggerIntervalSec seconds.

Available from iOS 10.

icon

String PushNotifications::Notification::icon

Required: name of an icon file (without an extension) to be used for this notification.

This must be the name of one of the image files included into resources when exporting an Android project (see "Extra Android Raw Resources" setting in Projucer).

channelId

String PushNotifications::Notification::channelId

Required for Android API level 26 or above: specifies notification channel id.

Refer to setupChannels(). Ignored on earlier Android versions.

largeIcon

Image PushNotifications::Notification::largeIcon

Optional: an additional large icon displayed in the notification content view.

tickerText

String PushNotifications::Notification::tickerText

Optional: ticker text used for accessibility services.

actions

Array<Action> PushNotifications::Notification::actions

Optional: actions associated with the notification.

Note that the OS may allow only a limited number of actions to be presented, so always present most important actions first. Available from Android API 16 or above.

progress

Progress PushNotifications::Notification::progress

Optional: set to default (0, 0, false), to disable progress display.

person

String PushNotifications::Notification::person

Optional: additional metadata used as a hint to OS that a notification is related to a specific person.

Can be useful for instance messaging apps. Available from Android API 21 or above.

type

Type PushNotifications::Notification::type = unspecified

Optional.

Available from Android API 21 or above.

priority

Priority PushNotifications::Notification::priority = medium

Optional.

Available from Android API 16 or above.

lockScreenAppearance

LockScreenAppearance PushNotifications::Notification::lockScreenAppearance = showPartially

Optional.

publicVersion

std::unique_ptr<Notification> PushNotifications::Notification::publicVersion

Optional: if you set lockScreenAppearance to showPartially, then you can provide "public version" of your notification that will be displayed on the lock screen.

This way you can control what information is visible when the screen is locked.

groupSortKey

String PushNotifications::Notification::groupSortKey

Optional: Used to order notifications within the same group.

Available from Android API 20 or above.

groupSummary

bool PushNotifications::Notification::groupSummary = false

Optional: if true, then this notification will be a group summary of the group set with groupId.

Available from Android API 20 or above.

accentColour

Colour PushNotifications::Notification::accentColour

Optional: sets accent colour.

The default colour will be used if accentColour is not set. Available from Android API 21 or above.

ledColour

Colour PushNotifications::Notification::ledColour

Optional: Sets the led colour.

The hardware will do its best to approximate the colour. The default colour will be used if ledColour is not set.

ledBlinkPattern

LedBlinkPattern PushNotifications::Notification::ledBlinkPattern

Optional.

vibrationPattern

Array<int> PushNotifications::Notification::vibrationPattern

Optional: sets the vibration pattern in milliseconds.

The first value indicates how long to wait until vibration starts. The second value indicates how long to vibrate. The third value will say how long to not vibrate and so on. For instance, if the pattern is: 1000, 2000, 3000, 4000 - then one second after receiving a notification the device will vibrate for two seconds, followed by 3 seconds of no vibration and finally, 4 seconds of vibration.

shouldAutoCancel

bool PushNotifications::Notification::shouldAutoCancel = true

Optional: If true, the notification will be automatically cancelled when a user clicks it in the panel.

localOnly

bool PushNotifications::Notification::localOnly = true

Optional: whether or not the notification should bridge to other devices.

Available from Android API 20 or above.

ongoing

bool PushNotifications::Notification::ongoing = false

Optional: If true, then it cannot be dismissed by the user and it must be dismissed manually.

Typically used for ongoing background tasks that the user is actively engaged with. To dismiss such notification, you need to call removeDeliveredNotification() or removeAllDeliveredNotifications().

alertOnlyOnce

bool PushNotifications::Notification::alertOnlyOnce = false

Optional: Set this flag if you would only like the sound, vibrate and ticker to be played if the notification is not already showing.

timestampVisibility

TimestampVisibility PushNotifications::Notification::timestampVisibility = normal

Optional.

badgeIconType

BadgeIconType PushNotifications::Notification::badgeIconType = large

groupAlertBehaviour

GroupAlertBehaviour PushNotifications::Notification::groupAlertBehaviour = alertAll

timeoutAfterMs

int PushNotifications::Notification::timeoutAfterMs = 0

specifies a duration in milliseconds, after which the notification should be cancelled, if it is not already cancelled.

Available from Android API 26 or above.

---

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

• juce_PushNotifications.h