A modern Android smartphone relies on a lot of services, from app stores and
calendars to messaging and push notifications. Most of them have open
alternatives, but until now, the only option for push notifications was
Google’s proprietary service, Firebase Cloud Messaging
(FCM). UnifiedPush is a new alternative that allows you to get push
notifications without being tied to a single company.

Push notifications are essential to the modern mobile experience because
they allow apps to communicate with users in real-time, even when not
actively in use. Relying on Google-provided push notifications is a concern
for both privacy and independence. The proprietary FCM library cannot be
included in F-Droid apps and relies on having Google services. As a result,
it is common to see FOSS applications adopt a persistent direct connection
between the application and the server as an alternative.

The limitations of direct app-server connections

While it is technically possible for each application to connect to its own
server and receive notifications directly, there are several reasons why
this approach may not be practical or effective.

Establishing and maintaining a direct connection between an app and a server
can be resource-intensive, which can strain the device’s battery, CPU, and
network resources.

• To minimize resource load, the operating system (OS) tries to suspend
  applications that are not actively in use. However, if each app actively
  maintains a server connection, the OS cannot suspend them.
• Multiple apps pinging their own servers at variable intervals can prevent
  the device from going into a low-power sleep mode, which can drain the
  device’s battery faster.
• Giving one special app the ability to make priority connections minimizes
  these problems and allows for the OS to efficiently suspend other
  applications and go to sleep, saving resources and reducing battery
  consumption.
• As a developer, managing background services and optimizing connections
  can be complex and time-consuming. By using a push notification service,
  you can offload this responsibility to a dedicated app, allowing you to
  focus on other aspects of your app.

How do I start with UnifiedPush, as a user?

Applications that support UnifiedPush can receive notifications via a
dedicated UnifiedPush application that maintains a single server connection
to receive all notifications. We call this “UnifiedPush application” a
distributor; it distributes push notifications to other apps on the
device. You can choose which distributor you want to use, self-host the
server part, or even create your own. For more information on distributors,
check out the full list.

To use UnifiedPush on an application that supports it, you have to install
and configure your distributor. You can use
UP-Example as a
simple test app.

All distributors are compatible with all apps

TL;DR on Android

The easiest way to set UnifiedPush up with an application that supports
it is to:

1. Install the ntfy Android application;
   this is your distributor
2. Open it, and disable battery optimization for it
3. Turn on UnifiedPush in the application; it will detect ntfy
   automatically. (This step depends on the app’s UX)

When there are multiple distributors available (yes, I know I have too many
:P), you can pick between them. When there’s just one, it is automatically
selected.

How to add UnifiedPush support to my app, as a developer?

To add UnifiedPush support to your application, you first need to ensure
that your server is UnifiedPush compatible: it must be able to send
notifications to different endpoints, which are URLs pointing to various
servers used by users. If your application uses a gateway to work with
Google push notifications, modifying the gateway can make it compatible with
UnifiedPush.

On the mobile app side, once the user enables UnifiedPush, you have to check
for installed distributors on the user’s device. The app should then prompt
the user to select the distributor they want to use. Afterward, you can
register with it.

The selected distributor will then send a new endpoint, which the
application should forward to its server. Then, the app prepares to receive
data sent to that endpoint by registering an Android BroadcastReceiver. This
BroadcastReceiver handles the messages coming from your server (often a ping
to fetch the notifications).

It is important to register the application with the selected distributor
every time the application starts, in case they get out of sync. If the
application receives the same endpoint again, it does not need to
re-register it.

Most of this is handled by the UnifiedPush library. You can find more
detailed instructions on our documentation
website.

If you need help with implementing UnifiedPush in your app, we are happy to
answer any questions you have on our Matrix
chat.

Note: This blog post focuses on Android; instructions to add UnifiedPush support on a Linux application can be found on our website.

How does UnifiedPush work under the hood?

At its core, UnifiedPush is a specification. That specification is split
into two halves:

• On the device (client) side, it defines an Application Programming
  Interface (API) to allow any end-user application (ex. your messaging
  app) to communicate with any distributor application (ntfy, NextPush,
  etc.)
• On the server side, the API describes how the application server
  (Matrix homeserver, Mastodon instance, etc.) sends messages to the push
  server (ntfy server, Nextcloud server, etc.).

Our client libraries and the reference proxies assist in implementing both
sides of the specification, respectively.

To obtain a UnifiedPush endpoint (capability URL to send notifications to),
the end-user application registers with the UnifiedPush distributor, which
maintains a constant connection with the push server. Upon registration, the
distributor provides the application with a unique URL pointing to the push
server. This endpoint URL is then transmitted by the application client to
the application server.

When the application server needs to send a push message to the end-user
application, it sends the message to the push server with a simple HTTP POST
request. The push server then forwards the push message to the distributor,
which delivers it to the end-user application.

One key feature of UnifiedPush is that the communication between the push
server and the distributor is not specified. This means that a variety of
technologies can be employed, such as WebSockets, Server-Sent Events, XMPP,
raw TCP, or even SMS, whatever works best for the user.

The distributor uses platform-specific IPC mechanisms, such as Broadcast
Intents on Android or D-Bus on Linux, to wake the app and allow it to handle
the push message. The app can then process the data and decide whether to
show a notification based on the content. It is important to note that
UnifiedPush does not handle the display of user-visible notifications; it
only delivers data to the app. Consequently, apps can support notification
features in various platforms without involvement from UnifiedPush or the
server.

In cases where the application server does not natively support UnifiedPush,
a Push Gateway can convert application-specific notifications to the
UnifiedPush server protocol. Some popular Push Gateways, such as the one for
Matrix, are integrated directly into push servers for self-hosting
convenience. In addition, Rewrite Proxies are used in rare cases where the
push server does not support UnifiedPush, such as the FCM distributor
sending UnifiedPush-over-FCM.

Push
Provider = Push Server

Compatibility between UnifiedPush and WebPush

Now, you might be looking at the elephant in the room: WebPush
(RFC8030). WebPush is the open standard that browsers use for their push
notifications. And the good news is that UnifiedPush is WebPush compatible
… mostly.

Basically, application servers that support WebPush but do not need its
advanced features and do not restrict push to only popular WebPush
servers (those from browser vendors) should work without problems with
UnifiedPush providers. We are working on solutions to ensure better and more
stable WebPush support.

Future plans

• The more apps that adopt UnifiedPush, the more useful it
  becomes. Currently, UnifiedPush is supported by many Matrix and Mastodon
  apps. We are also working on getting open-source versions of popular apps
  such as Telegram and Signal to support UnifiedPush.
• Improving WebPush support will also help to increase the number of apps
  that can use UnifiedPush. We are working towards better WebPush
  compatibility with UnifiedPush.
• What about built-in distributors in custom Android ROMs like Lineage OS or
  /e/OS (murena)? Their support could hugely accelerate UnifiedPush-support
  in the De-Googled community.
• Linux platforms can also benefit from UnifiedPush. Improving the Linux
  specification and increasing its adoption will help improve battery life
  and reactivity.
• As UnifiedPush is very flexible, some platforms could achieve even greater
  efficiency gains by using low-power hardware for the distributor: keeping
  it on the modem or a low-power core while the phone is asleep.

At the end of the day, if you use a Matrix or Mastodon app or one of the
other supported apps on Android,
there’s a good chance that you can use UnifiedPush to get your push
notifications without relying on Google. You can start using UnifiedPush
today by just installing ntfy or
choosing another distributor.

If you are an app developer interested in your app receiving push
notifications when installed from F-Droid and allowing your users to have
independent, self-hosted infrastructure, check out UnifiedPush and feel free
to talk to us if you have any
questions!