juce_PushNotifications.h

Go to the documentation of this file.

/*
  ==============================================================================
 
   This file is part of the JUCE library.
   Copyright (c) 2022 - Raw Material Software Limited
 
   JUCE is an open source library subject to commercial or open-source
   licensing.
 
   By using JUCE, you agree to the terms of both the JUCE 7 End-User License
   Agreement and JUCE Privacy Policy.
 
   End User License Agreement: www.juce.com/juce-7-licence
   Privacy Policy: www.juce.com/juce-privacy-policy
 
   Or: You may also use this code under the terms of the GPL v3 (see
   www.gnu.org/licenses).
 
   JUCE IS PROVIDED "AS IS" WITHOUT ANY WARRANTY, AND ALL WARRANTIES, WHETHER
   EXPRESSED OR IMPLIED, INCLUDING MERCHANTABILITY AND FITNESS FOR PURPOSE, ARE
   DISCLAIMED.
 
  ==============================================================================
*/
 
#pragma once
 
namespace juce
{

class JUCE_API PushNotifications    : private DeletedAtShutdown
{
public:
   #ifndef DOXYGEN
    JUCE_DECLARE_SINGLETON (PushNotifications, false)
   #endif
 
    //==============================================================================
    struct Notification
    {
        Notification() = default;
        Notification (const Notification& other);

        bool isValid() const noexcept;

        struct Action
        {
            enum Style
            {
                button,                    
                text                       
            };

            Style  style = button;
            String title;                 
            String textInputPlaceholder;  
            var    parameters;            

            String  identifier;                    
            bool    triggerInBackground = false;   
            bool    destructive = false;           
            String  textInputButtonText;           

            String       icon;            
 
            StringArray allowedResponses; 
        };
 
        //==============================================================================
 
        String identifier;   
 
        String title;        
        String body;         
        String subtitle;     
 
        String groupId;      
 
        int badgeNumber = 0; 
        URL soundToPlay;     
 
        var properties;      

 
        //==============================================================================
 
        String category;                
        double triggerIntervalSec = 0.; 
        bool   repeat = false;          

 
        //==============================================================================
 
        String icon;             
 
        String channelId;       
 
        Image largeIcon;        
 
        String tickerText;      
 
        Array<Action> actions;  

        struct Progress
        {
            int  max = 0;               
            int  current = 0;           
            bool indeterminate = false; 
        };
 
        Progress progress;       

        enum Type
        {
            unspecified,       
            alarm,             
            call,              
            email,             
            error,             
            event,             
            message,           
            taskProgress,      
            promo,             
            recommendation,    
            reminder,          
            service,           
            social,            
            status,            
            system,            
            transport          
        };

        enum Priority
        {
            veryLow  = -2,
            low      = -1,
            medium   =  0,
            high     =  1,
            veryHigh =  2
        };
 
        String person;               
 
        Type type = unspecified;     
        Priority priority = medium;  

        enum LockScreenAppearance
        {
            dontShow       = -1,  
            showPartially  =  0,  
            showCompletely =  1   
        };
 
        LockScreenAppearance lockScreenAppearance = showPartially;  
 
        std::unique_ptr<Notification> publicVersion; 
 
        String groupSortKey;         
        bool groupSummary = false;   
 
        Colour accentColour;  
        Colour ledColour;     

        struct LedBlinkPattern
        {
            int msToBeOn  = 0;   
            int msToBeOff = 0;   
        };
 
        LedBlinkPattern ledBlinkPattern; 
 
        Array<int> vibrationPattern;  
 
        bool shouldAutoCancel = true; 
 
        bool localOnly = true;  
 
        bool ongoing = false;   
 
        bool alertOnlyOnce = false; 

        enum TimestampVisibility
        {
            off,                    
            normal,                 
            chronometer,            
            countDownChronometer    
        };
 
        TimestampVisibility timestampVisibility = normal;  

        enum BadgeIconType
        {
            none,
            small,
            large
        };
 
        BadgeIconType badgeIconType = large;

        enum GroupAlertBehaviour
        {
            alertAll,           
            AlertSummary,       
            AlertChildren       
        };
 
        GroupAlertBehaviour groupAlertBehaviour = alertAll;
 
        int timeoutAfterMs = 0;    
    };
 
 
    //==============================================================================
    struct Settings
    {
        using Action = Notification::Action;

        struct Category
        {
            juce::String identifier;         
            juce::Array<Action> actions;     
            bool sendDismissAction = false;  
        };
 
        bool allowSound = false;      
        bool allowAlert = false;      
        bool allowBadge = false;      
        Array<Category> categories;   
    };

    void requestPermissionsWithSettings (const Settings& settings);

    void requestSettingsUsed();
 
    //==============================================================================
    struct Channel
    {
        String identifier;          
        String name;                

        enum Importance
        {
            none,
            min,
            low,
            normal,
            high,
            max
        };
 
        Importance importance = normal;     
        Notification::LockScreenAppearance lockScreenAppearance = Notification::showPartially;  
 
        String description;                 
        String groupId;                     
        Colour ledColour;                   
        bool bypassDoNotDisturb = false;    
        bool canShowBadge = false;          
        bool enableLights = false;          
        bool enableVibration = false;       
 
        URL soundToPlay;                    
        Array<int> vibrationPattern;        
    };

    struct ChannelGroup
    {
        String identifier;                  
        String name;                        
    };

    void setupChannels (const Array<ChannelGroup>& groups, const Array<Channel>& channels);
 
    //==============================================================================
    void getPendingLocalNotifications() const;

    void removePendingLocalNotification (const String& identifier);

    void removeAllPendingLocalNotifications();
 
    //==============================================================================
    bool areNotificationsEnabled() const;

    void sendLocalNotification (const Notification& notification);

    void getDeliveredNotifications() const;

    void removeDeliveredNotification (const String& identifier);

    void removeAllDeliveredNotifications();
 
    //==============================================================================
    String getDeviceToken() const;

    void subscribeToTopic (const String& topic);

    void unsubscribeFromTopic (const String& topic);

    void sendUpstreamMessage (const String& serverSenderId,
                              const String& collapseKey,
                              const String& messageId,
                              const String& messageType,
                              int timeToLive,
                              const StringPairArray& additionalData);
 
    //==============================================================================
    struct Listener
    {
        virtual ~Listener() = default;

        virtual void notificationSettingsReceived (const Settings& settings) { ignoreUnused (settings); }

        virtual void pendingLocalNotificationsListReceived (const Array<Notification>& notifications) { ignoreUnused (notifications); }

        virtual void handleNotification (bool isLocalNotification, const Notification& notification) { ignoreUnused (isLocalNotification); ignoreUnused (notification); }

        virtual void handleNotificationAction (bool isLocalNotification,
                                               const Notification& notification,
                                               const String& actionIdentifier,
                                               const String& optionalResponse)
        {
            ignoreUnused (isLocalNotification);
            ignoreUnused (notification);
            ignoreUnused (actionIdentifier);
            ignoreUnused (optionalResponse);
        }

        virtual void localNotificationDismissedByUser (const Notification& notification) { ignoreUnused (notification); }

        virtual void deliveredNotificationsListReceived (const Array<Notification>& notifications) { ignoreUnused (notifications); }

        virtual void deviceTokenRefreshed (const String& token) { ignoreUnused (token); }

        virtual void remoteNotificationsDeleted() {}

        virtual void upstreamMessageSent (const String& messageId) { ignoreUnused (messageId); }

        virtual void upstreamMessageSendingError (const String& messageId, const String& error) {  ignoreUnused (messageId); ignoreUnused (error); }
    };
 
    void addListener (Listener* l);
    void removeListener (Listener* l);
 
private:
    PushNotifications();
    ~PushNotifications() override;
 
    ListenerList<PushNotifications::Listener> listeners;
 
   #if JUCE_ANDROID
    friend bool juce_handleNotificationIntent (void*);
 
    friend struct JuceFirebaseInstanceIdService;
    friend struct JuceFirebaseMessagingService;
   #endif
 
  #if JUCE_PUSH_NOTIFICATIONS
    struct Pimpl;
    friend struct Pimpl;
 
    std::unique_ptr<Pimpl> pimpl;
  #endif
};
 
} // namespace juce