Troubleshooting UnifiedPush

Let's take charge of another part of our digital life! Must we be beholden to Google for delivering our push notifications? No! No longer! With apps that support UnifiedPush neither Google nor the app makers get to determine where our data goes and who gets to monitor it. We get the control, the freedom to choose.

To me this feels like a breath of fresh air!

You might find your way here while installing an app that uses UnifiedPush. Let's see how to make sure the notifications work properly.

The official UnifiedPush Troubleshooting page is, at the time of this writing, rather bare. (Perhaps, as an open source project, I can contribute to it. EDIT: Here's a preview I have submitted on Codeberg, that's becoming better than this article.) Meanwhile, read on.

Following my earlier articles such as Who Cares Who Delivers Our Notifications? and how to self-host UnifiedPush notifications for your Matrix server with ntfy, here are some tips for using a UnifiedPush-compatible app on your Android phone or your freedom-supporting (degoogled) android-compatible.

Install a Distributor to Enable UnifiedPush

Some U-P Distributors: ntfy, NextPush, Conversations, ...

The first step to using UnifiedPush is to get a UnifiedPush “distributor” app running and configured. A distributor is the one app that will be listening all the time on your device, on behalf of all the apps that want to receive UnifiedPush notifications. When notifications arrive, it will distribute them to the correct target apps (usually messaging apps).

Ideally, in the near future, freedom phones would include a UnifiedPush distributor built-in. For now, you have to install one.

You choose your distributor app once, the first time you want to start using UnifiedPush. The distributor works in concert with one UnifiedPush server (again, your choice, depending on what the distributor supports), so consider which server or service provider you want to use. Install the distributor app, and configure it according to its documentation. Some are preconfigured to use one particular server, while others allow or require you to choose a server.

The distributor must be working before any U-P-compatible app will be able to use UnifiedPush. If no distributor is detected, most apps will choose an alternative method, usually either polling or the proprietary Google system. However, if a distributor is installed but not working properly, notifications may not arrive promptly and consistently or at all.

Follow the instructions for your chosen combination of server and distributor, or start from the UnifiedPush Distributors page.

Troubleshooting UnifiedPush

Now we assume you have installed a U-P-compatible client app, perhaps a messaging app, and are expecting it to use UnifiedPush.

The general expectation is the app should “just work”, without even telling you, if it detects a functioning UnifiedPush distributor as described above.

How does this magic work? Three steps. First, your app asks the distributor on the same device for the details of your chosen UnifiedPush service. Second, your app passes those details on to its own server (wherever that is). Third, even after your app has disconnected from its own server or “gone to sleep”, your app's server continues to use those details to push notifications to your UnifiedPush server, which delivers them to your distributor, which delivers them to your app, waking it up.

Let's see what we can check if it does not seem to “just work”.

Check your app is supported and the right variant

First check that the client app you are using supports UnifiedPush. The UnifiedPush web site lists some of the first U-P-compatible apps. Some apps come in different variants, with for instance the variant available through the Google Play store using Google's notification system while the variant available though the F-Droid freedom-software store uses UnifiedPush. Some apps give you a choice if they detect both methods are available, and some choose one method without asking you.

Use the simple UP-Example app

Install the UnifiedPush troubleshooting app UP-Example from F-Droid. Use it to manually test UnifiedPush registration and operation: simply press the “register” button and then the “test” button, and you should immediately receive an example notification named “Test”.

If this simple test fails, you need to debug your UnifiedPush distributor app and its configuration.

(TODO: see troubleshooting for specific distributors 'ntfy', 'Conversations', 'NextPush', etc.)

Use advanced notification troubleshooting tools

You can find more advanced notification troubleshooting tools in some apps.

Element-Android and Schildichat-Android have a useful, active, troubleshooting tool in “Settings –> Notifications –> Troubleshoot Notifications”. In particular the “Gateway” and “Endpoint” steps of that troubleshooter should display your ntfy server's URL that it has discovered from the ntfy client app.

Check also “Settings –> Notifications –> Notification Targets” in Element or SchildiChat, or “Settings –> Notifications –> Devices” in FluffyChat. There should be one entry for each matrix client app that has enabled push notifications, and when that client is using UnifiedPush you should see a URL that begins with your ntfy server's URL.

In the “Notification Targets” screen in Element or SchildiChat, two relevant URLs are shown, “push_key” and “Url”, and both should begin with your ntfy server's URL. If “push_key” shows your server but “Url” shows an external server such as then push notifications are being routed through that external server before they reach your ntfy server, which might or might not be what you want.

Using your own UnifiedPush server

If you are running your own UnifiedPush server, of course you should also look at its logs and debugging capabilities. That is out of scope for this article.

These tips should help you resolve any issues

For further help, contact the most relevant or specific of the projects involved, such as your client app provider or your U-P distributor provider, or for more general help contact the UnifiedPush project, through the links provided here. (Note: The blog comments are for discussing the blog post, not for getting help.)

Once it is working, enjoy one more Google-free, self-determined aspect of your digital life!

Read More about UnifiedPush

#degoogled #unifiedPush #awesomeFOSS

Follow/Feedback/Contact: RSS feed · Fedi follow this blog: @julian​ · use the Cactus Comments box above · matrix me · Fedi follow me · email me · Donate: via Liberapay All posts © Julian Foad and licensed CC-BY-ND except quotes, translations, or where stated otherwise