Your setup

This page helps you resolve problems if an app is not working with UnifiedPush. It is aimed at general users who might be trying to use UnifiedPush for the first time.

First check these requirements and expectations.

You need several components to use UnifiedPush.

• Your App, for example a messaging app (on your device)
• … listening to a UnifiedPush Distributor (also on your device)
• … listening to a UnifiedPush Push Server (somewhere else)
• … listening to Your App’s App Server (such as a messaging server).

For everything to work:

• Your App must be able to communicate with the Distributor.

Any UnifiedPush-compatible application works with any Distributor. You have to be sure the application supports UnifiedPush. Some applications quietly detect and use your Distrbutor, so don’t expect Your App to need any UnifiedPush configuration.

In general, all UnifiedPush configuration (such as details of its Server) is done in the distributor, not in Your App.

For further details, see Check Your App Supports UnifiedPush.

• Your distributor must be able to communicate with the Push Server.

There should not be any problem, except if you self-host your server. There is an Example application to test this setup.

For further details, see The Distributor.

• The Push Server must be able to communicate with the App Server.

There might be network or configuration issues if you self-host the Push Server or the App Server. If you use public servers, your App Server may be rate-limited.

For further details, see The Push Server and Rate Limits.

Check that your specific app version and variant claims to support UnifiedPush.

• See some Apps using UnifiedPush.
• Some apps come in different variants, such as a Google Play store variant and an F-Droid variant, and they may support different push methods. Check that the variant you are using is documented as supporting UnifiedPush. In general it is more likely in a variant described with terms like “F-Droid” or “deGoogled” or “libre”.
• An app can support multiple push methods, and if it detects more than one it might ask you to choose or might choose for you. If this seems a possible cause of it failing to use UnifiedPush, try force-stopping and then restarting the app, which may make it re-check or re-ask the question.

You need to choose, install and configure a UnifiedPush distributor, which is available as an app. Follow its instructions carefully. It will need special permissions as it has to stay running in the background.

To check if you already have a UnifiedPush distributor installed, you can:

• use the example app (see Troubleshooting with the UP-Example App (Android) or Troubleshooting with the Example App (Linux)): if the Register function succeeds, then a distributor is installed;
• search your installed apps for ones named in the UnifiedPush distributor documentation.

On Linux, you can list registered and running distributors using the command dbus-send --print-reply --dest=org.freedesktop.DBus /org/freedesktop/DBus org.freedesktop.DBus.ListNames | grep org.unifiedpush.Distributor.

• Rate limits

Consider who provides the Push Server for you. It may have limitations, such as rate limits, especially if it’s provided to you free-of-charge. This is one case where a simple test may not show a problem, but real push notifications may not arrive.

For instance, see ntfy.sh limitations.

• App server to Push Server

If you self-host your Push Server, the App Server may not be able to reach your Push Server. You can check if you have a problem with the App Server not able to reach your Push Server by testing with another Distriutor, see Troubleshooting with a Distributor App

If you self-host your App Server, there might be network errors, or specific configuration to add. You can check if another App Server can reach your push server, see Troubleshooting with Other Apps.

For ntfy self-hosters, there is a specific troubleshooting page : Troubleshooting Self-Hosted Ntfy Servers.

For matrix self-hosters, there is a specific troubleshooting page : Troubleshooting Self-Hosted UnifiedPush and Matrix Servers.

You can test the Distributor and Push Server using the simple UP-Example app. Install it from F-Droid.

Click the Register button and then the Send notification button. You should immediately receive an example notification.

• If it won’t register, then your distributor is not correctly configured with your push server.
• If you have an error while testing the push notifications, then your push server is not correctly configured.
• If you don’t have an error and you don’t receive a notification, then your distributor is not correctly configured with your push server.
• If you do receive this test notification, then the problem may be in Your App. See The Push Server and Rate Limits.

You can test the Distributor and Push Server using the example app. Install it from codeberg:

• Download the latest zip
• Unzip it
• Open unifiedpush_example

Click the Register button and then the Notify button. You should immediately receive an example notification.

• If it won’t register, then your distributor is not correctly configured with your push server.
• If you have an error while testing the push notifications, then your push server is not correctly configured.
• If you don’t have an error and you don’t receive a notification, then your distributor is not correctly configured with your push server.
• If you do receive this test notification, then the problem may be in Your App. See The Push Server and Rate Limits.

Your Distributor app may display all active UnifiedPush registrations made through it. When you click on the Register button of the example app, an entry appears immediately in this list. And when you unregister, it should disappear. Some application may register multiple time, since is normal

With KUnifiedPush, you can get this list with a command line grep ServiceName ~/.config/KDE/kunifiedpush-distributor.conf.

Your Distributor may also show a counter of push notifications received for a registration. When you click on Send notification or Notify, this counter should increase.

You can find notification troubleshooting tools and information in some apps. It might be worth installing one of them in order to use these tools.

Some Matrix apps including Element, Element-X and Schildichat contain a useful, active, troubleshooting tool in “Settings -> Notifications -> Troubleshoot Notifications”, which performs several checks and displays the results. Note the reported “Gateway” and “Endpoint” URLs.

In the “Settings -> Notifications -> “Troubleshoot notifications” screen in Element-X (or Element or Schildichat), the push gateway URL is shown.

If this URL shows some other server (such as up.schildi.chat, or matrix.gateway.unifiedpush.org) then push notifications are being routed through that other server. This other server is called a gateway and is required to convert the matrix protocol to Web Push, as Matrix don’t support Web Push yet.

Some distributors (such as ntfy and NextPush) have a built-in matrix gateway: the gateway should be your push server.