如何實現支援 UnifiedPush? How to implement UnifiedPush support?

[yoyo930021]

簡介

UnifiedPush 可以說是 WebPush 技術在 Android 上的實現。

Web Push

跟使用者要推播權限 -> 瀏覽器產生 web push 的 payload -> 前端把 web push 的 payload 傳給後端 -> 後端儲存 payload 並跟使用者關聯 -> 後端按照 web push 的 payload 傳送通知到推播伺服器 -> 推播伺服器傳送通知給瀏覽器 -> 前端接收到通知顯示通知。

web push 的 payload

裡面是主要有 Endpoint 與 vapid 的驗證資訊，前者為要傳送 webpush 的推播伺服器的 API 端點，後者為多個非對稱式加密的欄位，驗證來源使用。
Endpoint 一般由瀏覽器提供，但每個瀏覽器會提供專屬於該用戶的網址，用以辨識。像是 Chrome 背後由 FCM 提供支持，會拿到一段 https://fcm.googleapis.com/fcm/xxxxxxxxxxxxxxx 。

UnifiedPush

跟 WebPush 差別在 Endpoint 一般為瀏覽器固定提供一個專屬於該客戶端的 API EndPoint，在 UnifiedPush 該 Endpoint 由使用者安裝且指定的分發器 (Distributors) 提供。UnifiedPush 利用 Android 內的廣播機制，讓使用 UnifiedPush 的 APP 可以透過廣播跟已經安裝的分發器的 APP 溝通取得 WebPush 的 payload 。以及流程上由 分發器 (Distributors) 收到通知後，在透過廣播機制給使用的 UnifiedPush 的 APP 接收，並實際顯示通知。
這樣就避免了實際每個 APP 都要建立一個持久連線的問題的同時，因為推播伺服器可以自架，也可以保證其隱私。

也就是說只要是後端支援 Web Push ，一般可以無痛支援 UnifiedPush 。

分發器 Distributors

簡單說就是實際推送到使用者手機的推播伺服器與其 APP ，推播伺服器可以自己架，也可以用網路上現成的服務。本身會透過廣播機制與實際使用
UnifiedPush 的 APP 做溝通。

• Sunup
  • 基於 Firefox WebPush Server 做的分發器，也就是說透過 Mozilla 服務來當推播伺服器。對使用者來說，使用起來最方便，安裝完 APP 就能直接使用。
• ntfy
  • 一套包含開源自架推播伺服器與雲端服務的分發器
• NextPush
  • 可以利用自架的 Nextcloud Server ，安裝 Nextcloud 的 APP ，來當快速架設專屬於自己的推播伺服器。
• gCompat-UP
  • 基於 FCM 的推播伺服器，官方建議只用開發與測試用途。

UnifiedPush 沒有限制要用什麼協議實際傳送推播訊息給用戶，所以也有基於 XMPP, Martix 等等現有協議的分發器，甚至你想要也可以用 SMS, Email 當載體。

embedded_fcm_distributor

官方提供的一種 fallback 方式，假如使用者沒有安裝任何的分發器，可以 fallback 到這個使用 FCM WebPush 的實現。該實現沒有使用任何 Google 專有的 lib ，因為它是基於 FCM 對 WebPush 的支持來製作的。

後端實作方案

1. 嘗試 hack OneSignal (或 FCM) 的方案

OneSignal 本身也有提供 WebPush 的支持，所以理論上也可以把 WebPush 的 Payload 與使用者的對應存在 OneSignal，但 OneSignal WebPush 要使用其官方的 JS SDK (附帶一題，好像有開源)，無法確認其後端是否有封鎖或額外的檢查，需進一步的研究，有較高的風險。

2. 讓每個活動的伺服器實現 WebPush 支援

CCIP-Server 透過 python 的 Webpush 套件，發出 WebPush 請求與儲存與使用者對應關係在 MongoDB 中。好處是維持現在分散式的架構，壞處是隨著活動消失，就無法給對應活動的使用者推播。

3. 自建一個小型的實現

透過 Hono 或 nitro 等支援 Serverless 與 Node 環境的框架，實現一個可以部屬在 Cloudflare Worker 或其他 Serverless 服務，甚至是一般機器上的專門處理 OPass 推播的服務。

⸻

Introduction

UnifiedPush can be considered as the implementation of WebPush technology on Android.

Web Push

The process:
Request push notification permission from the user → The browser generates the WebPush payload → The frontend sends the payload to the backend → The backend stores the payload and associates it with the user → The backend sends a notification to the push server according to the WebPush payload → The push server delivers the notification to the browser → The frontend receives and displays the notification.

WebPush Payload

The payload mainly contains the Endpoint and VAPID authentication information. The former is the API endpoint of the push server to which the WebPush will be sent, and the latter includes multiple fields of asymmetric encryption used for source verification.
The Endpoint is usually provided by the browser, but each browser gives a unique URL for each user for identification. For example, Chrome uses FCM behind the scenes, resulting in an endpoint like https://fcm.googleapis.com/fcm/xxxxxxxxxxxxxxx.

UnifiedPush

The difference from WebPush is that while in WebPush the Endpoint is a unique API endpoint provided by the browser for the client, in UnifiedPush the Endpoint is provided by a Distributor chosen and installed by the user. UnifiedPush leverages Android’s broadcast mechanism, allowing apps that support UnifiedPush to communicate with the installed distributor app via broadcast to obtain the WebPush payload. Once a distributor receives a notification, it uses the broadcast mechanism to deliver it to the UnifiedPush-enabled app, which then displays the notification.

This avoids the need for each app to maintain its own persistent connection, while also enabling users to self-host push servers, ensuring privacy.

In short, as long as the backend supports WebPush, it can usually support UnifiedPush with little effort.

Distributors

In simple terms, distributors are the push servers and their corresponding apps that actually deliver notifications to the user’s device. The push server can be self-hosted or use an existing service. They communicate with UnifiedPush-enabled apps via Android broadcasts.

• Sunup
  • A distributor based on Firefox WebPush Server, meaning it uses Mozilla’s service as the push server. For users, this is the most convenient since notifications work right after installing the app.
• ntfy
  • A distributor that provides both an open-source self-hosted push server and a cloud service.
• NextPush
  • Uses a self-hosted Nextcloud server, where installing the Nextcloud app allows quick setup of a personal push server.
• gCompat-UP
  • A push server based on FCM. The official recommendation is to only use it for development and testing.

UnifiedPush does not restrict which protocol can be used to deliver push messages to users. Therefore, there are distributors based on XMPP, Matrix, and even carriers like SMS or Email can be used if desired.

embedded_fcm_distributor

An official fallback option. If the user has not installed any distributor, the system can fall back to this implementation, which uses FCM WebPush. This implementation avoids using Google’s proprietary libraries, since it is based on FCM’s support for WebPush.

⸻

Backend Implementation Options

1. Attempt to hack OneSignal (or FCM)

OneSignal itself supports WebPush, so in theory it could store the mapping between the WebPush payload and users. However, OneSignal WebPush requires its official JS SDK (which appears to be open source), and it is unclear if there are backend restrictions or extra checks. This approach requires further investigation and carries higher risk.

2. Add WebPush support to each event’s server

For example, CCIP-Server uses Python’s WebPush library to send WebPush requests and store user associations in MongoDB.
• Advantage: Maintains the current decentralized architecture.
• Disadvantage: Once an event ends, users associated with that event can no longer receive notifications.

3. Build a small dedicated implementation

Create a dedicated push service for OPass using frameworks like Hono or Nitro, which support Serverless and Node environments. This service could be deployed on Cloudflare Workers, other serverless platforms, or even on regular servers, specifically to handle OPass push notifications.

⸻

Would you like me to also prepare a condensed version (like an executive summary) in English that you can use directly in documentation or presentations?