[Push] Use new UnifiedPush mechanism to resolve default distributor

[rfc2822]

I just came across this issue (for nothing related). There is a mechanism to set a default distributor for users, and this is the one that should be used when many are available. I've made a guide for developers regarding this recently, it may interest you: https://unifiedpush.org/developers/ux/

Originally posted by @p1gp1g in #1737

[ArnyminerZ]

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.

So... maybe it's a good idea to allow choosing one when first setting up a push-supported account? Something like:

1. Set up account in DAVx⁵
2. Service detection detects a push-capable collection
3. Execute the snippet in the guide:

   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()
   }

4. If a default distributor was found, choose it. Otherwise show a dialog (the app is being shown) to select the distributor.

This would modify the behavior of #1774, and get rid of per-flavor preference, which I think I am not against of

[p1gp1g]

The 3rd step already shows a dialog to the user using the OS-picker (cf. screenshot behind for context). So I don't think it would be necessary to add another dialog step 4.

I think that if the user dismiss the OS picker, you can either:

• disable push
• if you use the embedded fcm distributor (which is FOSS), you may want to use it to fallback to the Play Service.

PS: Feedback for the UX guide is welcome, I did it recently so there may be things to improve !

[rfc2822]

@p1gp1g I tried to understand the new schema from the docs, but I'm just confused now.

1. It seems that if there's one installed distributor app (let's say Conversations) and an embedded one (FCM distributor embedded in DAVx5), the workflow always selects the installed one (Conversations) as default. However what happens if that one is not configured / working? I think there's quite a good chance that Conversations, ntfy etc are installed (because the user tried it out), but not configured/working (for instance XMPP server stopped working and has never been fixed). Is there then a way to switch to the embedded distributor without own dialogs?

2. "Use your own dialog before running tryUseDefaultDistributor"
   What does it mean? What should that dialog do? On the one hand it sounds like we don't need our own dialog anymore (because it's handled by the Intent chooser), but on the other side we shall use our own dialog?

3. How is this related to LinkActivityHelper? Do we need LinkActivityHelper at all and what for?

4. The reference code mentions useDefaultDistributor(), but the API docs only contain tryUseDefaultDistributor(). Is it the same thing? And why "try"?

5. tryUseDefaultDistributor and other calls take an Activity. In case of a Compose/Nav3 application with only one activity, is it this one? I guess it's only needed for passing the result from Intent chooser back? And this line in documentation:

   You may prefer to override onActivityResult of your own Activity and use LinkActivityHelper.startPickLinkActivityForResult instead.

   makes me completely confused …

Sorry for the amount of questions, but it's really hard to understand for me. Is there some guide that we can just follow?

[p1gp1g]

Thank you for the feedback! I will update the doc to improve things after the discussion

I will try to answer the different points, and I will probably use parts of the responses for the doc if it's clear enough. So please let me know If I'm not!

@p1gp1g I tried to understand the new schema from the docs, but I'm just confused now.

1. It seems that if there's one installed distributor app (let's say Conversations) and an embedded one (FCM distributor embedded in DAVx5), the workflow always selects the installed one (Conversations) as default. However what happens if that one is not configured / working? I think there's quite a good chance that Conversations, ntfy etc are installed (because the user tried it out), but not configured/working (for instance XMPP server stopped working and has never been fixed). Is there then a way to switch to the embedded distributor without own dialogs?

There are different questions:

1. As you said, the installed distributor is always privileged with tryUseDefaultDistributor and similar functions.
2. Conversations or ntfy are 2 distributors that their main purpose isn't UnifiedPush. So, some users may have them installed without UnifiedPush support. In this case the UnifiedPush interface should be disabled and shouldn't be seen by the application. I know Conversations does it correctly, but I've just tested with ntfy and they don't do that correctly, I've to open a PR :) (EDIT: the PR is open)
3. My comment at the origin of the issue, and the documentation section to select the default distributor, are about selection the distributor when the feature is enabled. For instance, during onboarding to enable UnifiedPush by default if available.
4. That's good to keep an option to select a non-default distributor

If I understand correctly, the documentation doesn't talk enough about the embedded distributor.

So there 2 ways apps currently implement the embedded distributor:

1. As a fallback when UnifiedPush is disabled
   • If UnifiedPush is disabled because the user has turned off the feature, or because they don't have any distributor installed, the application tries to use the embedded distributor
   • if the app can't use the embedded distributor, it falls back to another solution, like a periodic worker
   • In this case, using tryUseDefaultDistributor when the setting is enabled is fine, because the setting is explicitly to use push via another app
2. As a choice, like any other distributor.
   • The application implements their own selection dialog, and FCM is an entry.
   • If UnifiedPush is disabled, the app falls back to another solution, like a periodic worker

If the application developers wants to give an option to completely disable push notifications: with the 1st option, it must be done via another setting and with the 2nd "Disable push" can simply be an entry in the selection.

The current documentation is more with the 1st idea, but if it makes more sense in the context of the application to be able to disable push notifications here, I think the 2nd is probably fine.

DAVx5 uses the 2nd option in the settings. I think you can keep your dialog you have in the settings, but simply use tryUseDefaultDistributor if you want to enable the feature during onboarding.

2. "Use your own dialog before running tryUseDefaultDistributor"

What does it mean? What should that dialog do? On the one hand it sounds like we don't need our own dialog anymore (because it's handled by the Intent chooser), but on the other side we shall use our own dialog?

Concretely, you simply show "You are about to select your UnifiedPush service" if UnifiedPush.resolveDefaultDistributor is ResolvedDistributor.ToSelect. You don't have to implement a selection dialog. Maybe I should reword a bit, and add a screenshot here

3. How is this related to LinkActivityHelper? Do we need LinkActivityHelper at all and what for?

When you use tryUseDefaultDistributor or related functions, it creates a transparent Activity to open the distributor LinkActivity. For some use case, you may need to integrate without this transparent Activity and you will have to use LinkActivityHelper, but you don't have to deal with it if truUseDefaultDistributor is fine.

4. The reference code mentions useDefaultDistributor(), but the API docs only contain tryUseDefaultDistributor(). Is it the same thing? And why "try"?

I think this is a very misleading thing I wrote. I will use a (close to) real-world example instead:

        when (val res = UnifiedPush.resolveDefaultDistributor(activity)) {
            is ResolvedDistributor.Found ->  {
                Log.d(TAG, "Found default distributor")
                preferences.isUnifiedPushEnabled = true
                UnifiedPush.saveDistributor(activity, res.packageName)
                registerUnifiedPushForAllAccounts(activity)
            }
            ResolvedDistributor.NoneAvailable -> {
                Log.d(TAG, "No default distributor")
                preferences.isUnifiedPushEnabled = false
            }
            ResolvedDistributor.ToSelect -> {
                Log.d(TAG, "Default distributor to select")
                activity.runOnUiThread {
                    showDistributorSelectionDialog(activity) { confirmed ->
                        if (confirmed) {
                            UnifiedPush.tryUseDefaultDistributor(activity) { res ->
                                if (res) {
                                    preferences.isUnifiedPushEnabled = true
                                    registerUnifiedPushForAllAccounts(activity)
                                } else {
                                    preferences.isUnifiedPushEnabled = false
                                }
                            }
                        } else {
                            Log.d(TAG, "Default distributor dismissed")
                            preferences.isUnifiedPushEnabled = false
                        }
                    }
                }
            }
        }

Note: Maybe I should add my prefix to any function that is supposed to be implemented by the developers.

5. tryUseDefaultDistributor and other calls take an Activity. In case of a Compose/Nav3 application with only one activity, is it this one? I guess it's only needed for passing the result from Intent chooser back? And this line in documentation:

That's the activity to give. Everything is handled automatically with this function

You may prefer to override onActivityResult of your own Activity and use LinkActivityHelper.startPickLinkActivityForResult instead.

makes me completely confused …

As I mentioned earlier about LinkActivityHelper, this is an "advanced" setup, but you don't have to deal with it if you don't need. I don't know how I should expose that clearly in the doc, nor where

Sorry for the amount of questions, but it's really hard to understand for me. Is there some guide that we can just follow?

No problem, that's a good moment to clarify our doc.

The guide is supposed to start here: https://unifiedpush.org/developers/intro/, then goes to https://unifiedpush.org/developers/ux/ and https://unifiedpush.org/developers/implementations/ where you can find the doc for the library you use: https://unifiedpush.org/kdoc/connector/