User Experience

This guide aims to give a reference for the UX regarding UnifiedPush support, in order to make all implementations more consistent.

Most of the time, UnifiedPush is transparent to the users. Most of the users have a single distributor installed on their system and never need to interact for anything.

Nevertheless, some cases must be thought in order to make things as friction less as possible:

• Users want to know that they are correctly registered to get notifications with UnifiedPush
• 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 distributors on their system and wish to use another one
• And finally, some users may delete their push service from their device

Therefore, a few things need to be visible to the user.

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

• A distributor should be referred as a “UnifiedPush Service” or a “Distributor App”, but never as a “UnifiedPush App”, as it may refer to the application connected to the distributor or the distributor itself.
• FCM should be referred as Play Services.

During the first setup of push notifications, for example during the on-boarding of the application, you may want to use a different default:

• No push notifications at all
• The play services if available
• UnifiedPush if available
• Onboarding screen

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

Because your application supports FCM (Play services) notifications for a while and the solution is proven effective, you may want to use them by default if they are available.

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

Caution

This default is about an FCM-only implementation of the push notifications. The fcm embedded distributor is handled with UnifiedPush default, and should not be used by default if the user has another distributor installed.

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

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

Note

As most users, if only one UnifiedPush distributor is installed on the system, this step will be transparent to the user.

If your application supports at least two ways to get notifications, may it be with UnifiedPush, the Play Services, or an internal connection.

First check if there are UnifiedPush distributors installed on the system and if the Play Services are available.

Then, depending on the status:

• If only one option is present: then you don’t need to show a screen. You can directly register to the service. (cf. try to use UnifiedPush default distributor
• If at least 2 options are present: offer a screen that lets the user chose what they prefer to use. Then register to the Play Services, or use the default UnifiedPush distributor

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 a default or a single 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 notification 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 service 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 fallback 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) than 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 more available but others are: You can try to use UnifiedPush default distributor.
3. The user wasn’t using UnifiedPush because no distributor were 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 use 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 notification 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 to work.
• VAPID_REQUIRED: Your application doesn’t support VAPID, you can exclude this distributor from the list of available distributors, and act as 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 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 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
)