User Experience

This guide aims to give a reference for the user experience (UX) regarding UnifiedPush support. The goal is to make implementations more consistent.

Most of the time, UnifiedPush is transparent to the users. Users generally have a single distributor installed on their system. Such users never really need to interact with the UnifiedPush system.

Nevertheless, some cases must be considered in order to make things as frictionless as possible:

• Users want to know that they are correctly registered to the UnifiedPush distributor
• Some users may have UnifiedPush and the Play Services on their system and want to switch from one service to the other
• Some users may have different UnifiedPush distributors on their system and wish to use another one
• Some users may delete their push service from their device

Therefore, in some cases a UI needs to be presented to the user.

In the user interface, you will have to refer to some concepts of UnifiedPush. In order to keep it simple and consistent, we suggest following these resources:

• A distributor should be referred to as a “UnifiedPush Service” or a “Distributor App”.
• A distributor must never be referred to as a “UnifiedPush App”, as users might confuse this with the application connecting to the distributor.
• FCM should be referred to as Play Services.

During the first setup of push notifications, for example during the on-boarding of the application, the developer can choose different default modes:

• No push notifications at all
• UnifiedPush if available
• The Play Services if available
• Onboarding screen

If you want to disable push notifications by default, the user will have to enable them in the settings.

If the user has one or more UnifiedPush distributors enabled on their system, it means they probably want to use UnifiedPush.

In this case, during the onboarding, you will try to set the UnifiedPush default distributor.

Note

Since most users only have one UnifiedPush distributor installed on the system, this step will be transparent to the user.

If your application already has support for FCM (Play Services) notifications, and you are unsure if UnifiedPush would be as effective, it’s completely fine to use FCM as default.

If the user doesn’t have Play Services, we recommend falling back to UnifiedPush if available.

Caution

This default should only be used if both UnifiedPush and FCM support are natively implemented in the app. The fcm embedded distributor expects that the app only supports UnifiedPush natively. Therefore, the embedded_fcm_distributor should not be used by default if the user has another distributor installed.

If your application supports at least two ways to get notifications — whether with UnifiedPush, the Play Services, or polling — then you should let the user choose.

First check if there are UnifiedPush distributors and/or Play Services available.

Then, depending on the status:

• If only one option is present, you don’t need to show a selection screen. You can directly register to the available service. (e.g., try to use UnifiedPush default distributor)
• If at least 2 options are present: offer a screen that lets the user choose what they prefer to use.

Trying to use the default distributor must always be done from a user view (an Activity on Android), as the user may need to select it manually. They may need to select it if they don’t have any default, or, on Android, if it’s the first time they select their default distributor.

When the user has set a default distributor, this operation is transparent to the user.

When the user has many distributors but hasn’t selected a default yet, the operation will need a screen to select one. Informing the user about the incoming OS screen helps them to understand why they are selecting an application.

When the user has to select a distributor, the user must be informed they are doing an action related to push notifications or UnifiedPush while selecting a push service: it can be done with a dialog description, or a dedicated view.

On Android

We recommend using resolveDefaultDistributor to check if the operation will require a user interaction.

when (val res = UnifiedPush.resolveDefaultDistributor(this)) {
    is ResolvedDistributor.Found -> useDefaultDistributor()
    ResolvedDistributor.ToSelect -> {
        // Use your own dialog before running tryUseDefaultDistributor
        showDialogBeforeSelection(
            this,
            onConfirmed = { useDefaultDistributor() },
            onDismissed = { fallbackToAnotherSolution() }
        )
    }
    ResolvedDistributor.NoneAvailable -> fallbackToAnotherSolution()
}

To actually select the distributor, we recommend using tryUseDefaultDistributor or tryUseCurrentOrDefaultDistributor. If the user has a default, or only one distributor is installed on the system, it will be transparent to the user. Else, it will show an OS dialog to choose the default distributor if it hasn’t been selected yet.

On Linux

The default distributor is retrieved using the environment variable UNIFIEDPUSH_DISTRIBUTOR. If it is set, you can use this distributor silently.

If the environment variable isn’t set, you need to list D-Bus services starting with org.unifiedpush.Distributor..

If only one is available, you can use it directly.

Else, if there are many distributors, you need to implement a dialog.

Important

If after trying to use the default distributor, the user hasn’t selected one, we recommend disabling UnifiedPush and falling back to another solution like the Play Services.

The user will have to enable UnifiedPush again in the settings if needed.

If your application supports multi-accounts, then we recommend using the same push method for all the accounts.

When the user adds a new account, you should register it the same way (UnifiedPush or Play Services) as the other accounts.

Important

With UnifiedPush, you must subscribe every account for a new registration: they must not share the same push endpoint.

On Android, you need to use a different registration instance for every account: register(ctx, instance=accountId)

If your application’s support for Web Push is in progress, and some users may support the protocol while others don’t, you can either:

• Require all users to support Web Push in order to offer UnifiedPush
• Fallback to another solution (Play Services) for users who don’t support Web Push yet.

Every time the application is starting, you should register all accounts with the distributor. During startup, you can be in different states:

1. The user was using UnifiedPush and the distributor is still available: register all accounts, even those that were unregistered. This can be done by scheduling a periodic job.
2. The user was using UnifiedPush and the distributor is no longer available but others are: You can try to use UnifiedPush default distributor.
3. The user wasn’t using UnifiedPush because no distributor was installed until then and at least one distributor is installed now: You can try to use UnifiedPush default distributor.
4. UnifiedPush is disabled by the user, or no distributor is available: fallback to another solution.

On Android

All these steps can be done using tryUseCurrentOrDefaultDistributor.

You can even use this method during the first time setup too.

We recommend giving an option to enable or disable UnifiedPush, even if the Play Services are available, even if the app always uses UnifiedPush.

It allows the user to control the applications that get push notifications and also indicates when UnifiedPush is correctly enabled.

This option should be hidden if only one distributor is installed on the system.

If UnifiedPush is enabled and many distributors are available on the system, we recommend giving an option to the user to select a non-default distributor.

On Android

Do not forget to exclude your own packageName from the getDistributors list to check for external services only.

Like when selecting the default distributor, the user must be informed they are doing an action related to push notifications or UnifiedPush while selecting a push service: it can be done with a dialog description, or a dedicated view.

On Android

We recommend using tryPickDistributor: it will show an OS dialog to choose another distributor.

The registration failures are rare events. The most likely to happen is a NETWORK failure. Most of the time, you can simply ignore the registration failures and let your application re-register itself during next startup. If you were already registered with the distributor, you will likely still be connected to the distributor.

The registration may fail for different reasons:

• INTERNAL_ERROR: This is a generic error type, you can try to register again directly once.
• NETWORK: The registration failed because of missing network connection, try again when network is back.
• ACTION_REQUIRED: You should inform the user that an action is required on the distributor for it to work.
• VAPID_REQUIRED: Your application doesn’t support VAPID, you can exclude this distributor from the list of available distributors, and act as if you were unregistered.

On Android

You can use a constrained OneTimeWorkRequest to re-register when you are connected to the network again.

The unregistrations are rare events too. It may happen if the distributor is logged out, or if the distributor has been uninstalled.

When you get an unregistration message:

1. You should remove the registration from the application server. If your application server removes the endpoint when the push notification request returns a 401/403/404/410, you can let it delete the registration itself.

2. You can schedule a job to re-register for UnifiedPush. We recommend scheduling a job executed a few seconds later. This avoids registering to the distributor while it is disconnecting for instance. If you’re using multi-account registrations, it will allow processing all your registrations at the same time.

3. During this re-registration work:

   1. If the saved distributor is still installed, and connected (getAckDistributor() is still the same), re-register to it
   2. If the saved distributor isn’t used anymore (getAckDistributor() is null), and there are distributors on the system: show a notification to inform the user that the application has been unregistered, with an action to open your application on click. Then you will be able to try to use UnifiedPush default distributor.
   3. If no distributors are available, you should show a notification to inform that UnifiedPush isn’t available anymore and fallback to another solution. You may need to add an action to your notification to start a special service on click.

On Android

 To schedule a job for a potential re-registration with multi-account, you can use a OneTimeWorkRequest, with an initial delay, unqueued as a unique work with a constant tag:

val work = OneTimeWorkRequest.Builder(workerClass)
  .setInitialDelay(10, TimeUnit.SECONDS)
  .build()
WorkManager.getInstance(context).enqueueUniqueWork(
  UNIQUE_ONETIME_WORK_TAG,
  ExistingWorkPolicy.REPLACE,
  work
)