User Experience

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

In the other interface, you will have to refere to some concept of UnifiedPush to the user. In order to keep it simple and consistent, we suggest to follow these resource:

• A distributor should be refered as a (We need to choose: “UnifiedPush Service”, “Distributor App”, “Push notification provider”?)
• FCM should be refered as Play Services.

During the onboarding, depending on your application, you may want to use a different default:

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

If your application supports multi-accounts, then we recommend to use the push method already selected for the onboarding of second accounts.

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 fallback to UnifiedPush if available.

Caution

This default is about a 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.

1. In this case the onboarding can silently process if it can get the user default distributor directly.
2. If it can’t be processed silently, the user must be informed they will have to choose a “UnifiedPush Service” (TODO: change following user resources), then ask the user the service to use (cf. note).
3. If there are distributors on the system and the user hasn’t selected one, UnifiedPush should be disabled. The user will have to enable them in the settings if needed.
4. If no distributor has been selected, or none are available, we recommend to fallback to Play Services if available.

Note

To get the default distributor silently:

• You can skip this step if your framework doesn’t give this feature.
• On Android, you can use UnifiedPush.TODO(). The embedded distributor is selected as a fallback if no other distributor is available.
• On Linux, you can look at the environment variable UNIFIEDPUSH_DISTRIBUTOR, or if there is a single distributor on the system.

To get the user distributor during onboarding:

• On Android, you should use UnifiedPush.tryUseCurrentOrDefaultDistributor
• On Linux, the selection must be implemented by the app developper

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 schedulling a periodic job.
2. The user was using UnifiedPush, and the distributor is no more available OR the user was not using UnifiedPush because no distributor were available until then, and one or more distributors has been installed:
   1. It was a default distributor => try to use the new default distributor silently, or inform the user they will have to choose a “UnifiedPush Service” and ask them their new default (cf. UnifiedPush default).
   2. It was a non-default distributor => inform the user they will have to choose a new “UnifiedPush Service” and ask them to pick one.
   3. If there are distributors on the system and the user hasn’t selected one, UnifiedPush should be disabled. The user will have to enable them in the settings if needed.
   4. If no distributor has been selected, or none are available, we recommend to fallback to Play Services if available.
3. UnifiedPush is disabled by the user, or no distributor is available: do nothing.

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

When the feature is disabled, Even if play services available.

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

Note

Do not forget to exclude your own packageName from the getDistributors list to check for external services. You can use UnifiedPush.pickDistributor on Android to select a non-default 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 failure 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.

Note

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

The unregistration is a rare event 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 removes endpoint on 404, you can let it delete the registration itself.
2. You should schedule a job to handle the potential re-registration. If you use a single UnifiedPush registration, it can be done directly, else you should wait a bit, to be sure you have a single job for all the unregistrations.
3. During this re-registration work:
   1. If the saved distributor is still used (e.g. by another account), re-register to it
   2. If the saved distributor isn’t used anymore, and it was the default distributor, try to silently get the new distributor and register all the accounts with it.
   3. Else, show a notification to the user to ask them to open the app to select a new distributor. The notification should open your app on click. Then you need to follow app startup steps.

Note

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
)