Add Silent Push notification to update Unread Notification Count in all situations

humhub/app-internal#74 and humhub/app#52

Author: marc-farre

Events.php

@@ -7,8 +7,10 @@
 use humhub\modules\fcmPush\components\NotificationTargetProvider;
 use humhub\modules\fcmPush\helpers\MobileAppHelper;
 use humhub\modules\fcmPush\helpers\WebAppHelper;
+use humhub\modules\fcmPush\jobs\SendSilentUnreadNotificationCountJob;
 use humhub\modules\fcmPush\services\ServiceWorkerService;
 use humhub\modules\fcmPush\widgets\RegisterDeviceTokenButton;
+use humhub\modules\notification\events\UnreadCountChangedEvent;
 use humhub\modules\notification\targets\MobileTargetProvider;
 use humhub\modules\notification\widgets\NotificationSettingsForm;
 use humhub\modules\web\pwa\controllers\ServiceWorkerController;
@@ -106,4 +108,25 @@ public static function onNotificationSettingsFormAfterRun(WidgetEvent $event)
             $event->result = RegisterDeviceTokenButton::widget() . $event->result;
         }
     }
+
+    /**
+     * Pushes a delayed, exclusive-per-user job that sends the updated unread notification
+     * count as a silent push to the user's devices, whenever the count changed.
+     *
+     * The delay collapses multiple count changes within a short time frame into a single
+     * push carrying the final count
+     */
+    public static function onUnreadCountChanged(UnreadCountChangedEvent $event): void
+    {
+        /** @var Module $module */
+        $module = Yii::$app->getModule('fcm-push');
+
+        if (!$module->getDriverService()->hasConfiguredDriver()) {
+            return;
+        }
+
+        Yii::$app->queue->delay($module->silentUnreadNotificationCountPushDelay)->push(new SendSilentUnreadNotificationCountJob([
+            'userId' => $event->user->id,
+        ]));
+    }
 }

Module.php

@@ -10,6 +10,14 @@
 class Module extends \humhub\components\Module
 {
     public string $humhubProxySenderId = '21392898126';
+
+    /**
+     * @var int delay in seconds before a silent unread notification count push is sent.
+     * Multiple count changes for the same user within this window are collapsed into a
+     * single push carrying the final count.
+     * @since 2.2.9
+     */
+    public int $silentUnreadNotificationCountPushDelay = 60 * 10;
     private ?ConfigureForm $configForm = null;
     private ?DriverService $driverService = null;
 

config.php

@@ -5,6 +5,7 @@
 
 use humhub\components\Controller;
 use humhub\modules\fcmPush\Events;
+use humhub\modules\notification\events\UnreadCountChangedEvent;
 use humhub\modules\notification\widgets\NotificationSettingsForm;
 use humhub\modules\user\components\User;
 use humhub\widgets\LayoutAddons;
@@ -23,6 +24,7 @@
         [User::class, User::EVENT_AFTER_LOGIN, [Events::class, 'onAfterLogin']],
         [User::class, User::EVENT_AFTER_LOGOUT, [Events::class, 'onAfterLogout']],
         [NotificationSettingsForm::class, NotificationSettingsForm::EVENT_AFTER_RUN, [Events::class, 'onNotificationSettingsFormAfterRun']],
+        [UnreadCountChangedEvent::class, UnreadCountChangedEvent::EVENT_UNREAD_COUNT_CHANGED, [Events::class, 'onUnreadCountChanged']],
     ],
     'consoleControllerMap' => [
         'firebase' => 'humhub\modules\fcmPush\commands\SendController',

docs/CHANGELOG.md

@@ -4,6 +4,7 @@ Changelog
 2.2.9 (Unreleased)
 ------------------
 - Enh #102: Calculate the notification badge count internally and allow other modules to add their own counts via the new `MessagingService::EVENT_NOTIFICATION_COUNT` event; the `$notificationCount` parameter of `MessagingService::processMessage()` is deprecated and its value ignored
+- Enh #103: Send a silent push notification with the updated unread notification count whenever it changes (e.g. after reading/seeing a notification or conversation message), so the app badge count stays in sync
 
 2.2.8 (July 15, 2026)
 ---------------------

drivers/DriverInterface.php

@@ -12,6 +12,14 @@ public function __construct(ConfigureForm $config);
 
     public function processCloudMessage(array $tokens, string $title, string $body, ?string $url, ?string $imageUrl, ?int $notificationCount): SendReport;
 
+    /**
+     * Sends a silent (data-only) message that only carries the unread notification count,
+     * without a visible notification. Used to keep the app badge count in sync.
+     *
+     * @since 2.2.9
+     */
+    public function processSilentCloudMessage(array $tokens, ?int $notificationCount): SendReport;
+
     public function getSenderId(): string;
 
     public function isConfigured(): bool;

drivers/Fcm.php

@@ -36,6 +36,27 @@ public function __construct(private ConfigureForm $config)
     }
 
     public function processCloudMessage(array $tokens, string $title, string $body, ?string $url, ?string $imageUrl, ?int $notificationCount): SendReport
+    {
+        $message = CloudMessage::new()
+            ->withNotification(Notification::create($title, $body)) // $imageUrl is intentionally omitted — including it would show a duplicate logo on branded apps
+            ->withWebPushConfig(['fcm_options' => ['link' => $url]])
+            ->withData(['url' => $url, 'notification_count' => $notificationCount])
+            ->withHighestPossiblePriority();
+
+        return $this->sendMulticast($message, $tokens);
+    }
+
+    public function processSilentCloudMessage(array $tokens, ?int $notificationCount): SendReport
+    {
+        // Data-only message (no notification payload) so the app updates the badge count
+        // in the background without displaying a visible notification.
+        $message = CloudMessage::new()
+            ->withData(['notification_count' => $notificationCount]);
+
+        return $this->sendMulticast($message, $tokens);
+    }
+
+    private function sendMulticast(CloudMessage $message, array $tokens): SendReport
     {
         if ($this->messaging === null) {
             Module::registerAutoloader();
@@ -44,12 +65,6 @@ public function processCloudMessage(array $tokens, string $title, string $body,
             $this->messaging = $factory->createMessaging();
         }
 
-        $message = CloudMessage::new()
-            ->withNotification(Notification::create($title, $body)) // $imageUrl is intentionally omitted — including it would show a duplicate logo on branded apps
-            ->withWebPushConfig(['fcm_options' => ['link' => $url]])
-            ->withData(['url' => $url, 'notification_count' => $notificationCount])
-            ->withHighestPossiblePriority();
-
         try {
             $report = $this->messaging->sendMulticast($message, $tokens);
         } catch (MessagingException $e) {

drivers/Proxy.php

@@ -42,15 +42,29 @@ public function createRequest()
 
     public function processCloudMessage(array $tokens, string $title, string $body, ?string $url, ?string $imageUrl, ?int $notificationCount): SendReport
     {
-        $data = [
+        return $this->sendCloudMessage([
             'tokens' => $tokens,
             'title' => $title,
             'body' => $body,
             'iconUrl' => $imageUrl,
             'url' => $url,
             'notificationCount' => $notificationCount,
-        ];
+        ]);
+    }
 
+    public function processSilentCloudMessage(array $tokens, ?int $notificationCount): SendReport
+    {
+        // A silent message carries no title/body, so the relay dispatches a data-only
+        // message that only updates the app badge count without showing a notification.
+        return $this->sendCloudMessage([
+            'tokens' => $tokens,
+            'notificationCount' => $notificationCount,
+            'silent' => true,
+        ]);
+    }
+
+    private function sendCloudMessage(array $data): SendReport
+    {
         $response = $this->post('/push', $data)->send();
 
         if (!$response->isOk || empty($response->data['success'])) {

jobs/SendSilentUnreadNotificationCountJob.php

@@ -0,0 +1,53 @@
+<?php
+
+namespace humhub\modules\fcmPush\jobs;
+
+use humhub\modules\fcmPush\Module;
+use humhub\modules\fcmPush\services\MessagingService;
+use humhub\modules\queue\ActiveJob;
+use humhub\modules\queue\interfaces\ExclusiveJobInterface;
+use humhub\modules\user\models\User;
+use Yii;
+
+/**
+ * Sends a silent (data-only) push notification carrying the current unread notification
+ * count to a user's registered devices, so the mobile / PWA app can update its badge count.
+ *
+ * This job is exclusive per user and is pushed with a delay (see the FCM push event handler),
+ * so multiple unread-count changes within a short time frame are collapsed into a single push
+ * carrying the final, up-to-date count.
+ *
+ * @since 2.2.9
+ */
+class SendSilentUnreadNotificationCountJob extends ActiveJob implements ExclusiveJobInterface
+{
+    /**
+     * @var int the id of the user whose unread notification count has changed
+     */
+    public $userId;
+
+    /**
+     * @inheritdoc
+     */
+    public function getExclusiveJobId()
+    {
+        return 'fcm-push.silent-unread-count.' . $this->userId;
+    }
+
+    /**
+     * @inheritdoc
+     */
+    public function run()
+    {
+        $user = User::findOne(['id' => $this->userId]);
+        if ($user === null) {
+            return;
+        }
+
+        /** @var Module $module */
+        $module = Yii::$app->getModule('fcm-push');
+
+        (new MessagingService($module->getConfigureForm()))
+            ->sendSilentUnreadNotificationCount($user);
+    }
+}

module.json

@@ -9,9 +9,9 @@
     ],
     "homepage": "https://github.com/humhub/fcm-push",
     "humhub": {
-        "minVersion": "1.18"
+        "minVersion": "1.19"
     },
-    "version": "2.2.8",
+    "version": "2.2.9",
     "screenshots": [
         "resources/screenshot1.PNG",
         "resources/screenshot2.PNG"

services/MessagingService.php

@@ -3,13 +3,13 @@
 namespace humhub\modules\fcmPush\services;
 
 use humhub\components\Event;
+use humhub\modules\fcmPush\components\SendReport;
 use humhub\modules\fcmPush\drivers\DriverInterface;
 use humhub\modules\fcmPush\events\NotificationCountEvent;
 use humhub\modules\fcmPush\models\ConfigureForm;
 use humhub\modules\notification\components\BaseNotification;
 use humhub\modules\notification\models\Notification as NotificationHumHub;
 use humhub\modules\user\models\User;
-use humhub\modules\web\pwa\widgets\SiteIcon;
 use Yii;
 use yii\helpers\Url;
 
@@ -39,32 +39,38 @@ public function processNotification(BaseNotification $baseNotification, User $us
             Yii::$app->name,
             $baseNotification->text(),
             Url::to(['/notification/entry', 'id' => $baseNotification->record->id], true),
-            $this->getSiteIconUrl(180),
+            Yii::$app->img->icon->getUrl(['square' => 180]),
         );
     }
 
     /**
-     * Returns the site icon URL for the given square size.
-     *
-     * HumHub 1.19 removed the {@see SiteIcon} widget and replaced it with the
-     * AssetImage registry exposed as `Yii::$app->img`. This module still supports
-     * HumHub 1.18 (see `module.json` `humhub.minVersion`), so fall back to the
-     * legacy widget when the registry is not available.
+     * @param int|null $notificationCount deprecated since 2.2.9, will be removed in a future version.
+     *        The value is ignored — the count is now calculated by {@see getNotificationCount()}.
      */
-    private function getSiteIconUrl(int $size): ?string
+    public function processMessage(User $user, string $title, string $body, ?string $url, ?string $imageUrl, ?int $notificationCount = null)
     {
-        if (Yii::$app->has('img')) {
-            return Yii::$app->img->icon->getUrl(['square' => $size]);
-        }
+        $tokenService = new TokenService();
+        $notificationCount = $this->getNotificationCount($user);
 
-        return SiteIcon::getUrl($size);
+        foreach ($this->drivers as $driver) {
+            $tokens = $tokenService->getTokensForUser($user, $driver);
+            if (empty($tokens)) {
+                continue;
+            }
+
+            $report = $driver->processCloudMessage($tokens, $title, $body, $url, $imageUrl, $notificationCount);
+            $this->removeFailedTokens($tokenService, $report);
+        }
     }
 
     /**
-     * @param int|null $notificationCount deprecated since 2.2.9, will be removed in a future version.
-     *        The value is ignored — the count is now calculated by {@see getNotificationCount()}.
+     * Sends a silent (data-only) push notification carrying the current unread notification
+     * count to the user's registered devices, so the mobile app (Proxy driver) and PWA app
+     * (Fcm driver) can update their badge count without displaying a visible notification.
+     *
+     * @since 2.2.9
      */
-    public function processMessage(User $user, string $title, string $body, ?string $url, ?string $imageUrl, ?int $notificationCount = null)
+    public function sendSilentUnreadNotificationCount(User $user): void
     {
         $tokenService = new TokenService();
         $notificationCount = $this->getNotificationCount($user);
@@ -75,14 +81,20 @@ public function processMessage(User $user, string $title, string $body, ?string
                 continue;
             }
 
-            $report = $driver->processCloudMessage($tokens, $title, $body, $url, $imageUrl, $notificationCount);
+            $report = $driver->processSilentCloudMessage($tokens, $notificationCount);
+            $this->removeFailedTokens($tokenService, $report);
+        }
+    }
 
-            // Remove tokens that Firebase rejected (e.g. from an uninstalled / reinstalled app).
-            // This prevents stale tokens from accumulating and blocking future deliveries.
-            foreach ($report->failedTokens as $failedToken) {
-                Yii::warning("Removing failed/unregistered FCM token: $failedToken", 'fcm-push');
-                $tokenService->deleteToken($failedToken);
-            }
+    /**
+     * Removes tokens that Firebase rejected (e.g. from an uninstalled / reinstalled app).
+     * This prevents stale tokens from accumulating and blocking future deliveries.
+     */
+    private function removeFailedTokens(TokenService $tokenService, SendReport $report): void
+    {
+        foreach ($report->failedTokens as $failedToken) {
+            Yii::warning("Removing failed/unregistered FCM token: $failedToken", 'fcm-push');
+            $tokenService->deleteToken($failedToken);
         }
     }