Setup knit TOC.
Only ## and more heading will be listed, so add a "h" level.
This commit is contained in:
Benoit Marty
parent
828e13f9be
commit
b3a5812a61
|
|
@ -1,28 +1,16 @@
|
|||
This document aims to describe how Element android displays notifications to the end user. It also clarifies notifications and background settings in the app.
|
||||
|
||||
# Table of Contents
|
||||
1. [Prerequisites Knowledge](#prerequisites-knowledge)
|
||||
* [How does a matrix client get a message from a homeserver?](#how-does-a-matrix-client-get-a-message-from-a-homeserver)
|
||||
* [How does a mobile app receives push notification?](#how-does-a-mobile-app-receives-push-notification)
|
||||
* [Push VS Notification](#push-vs-notification)
|
||||
* [Push in the matrix federated world](#push-in-the-matrix-federated-world)
|
||||
* [How does the homeserver know when to notify a client?](#how-does-the-homeserver-know-when-to-notify-a-client)
|
||||
* [Push vs privacy, and mitigation](#push-vs-privacy-and-mitigation)
|
||||
* [Background processing limitations](#background-processing-limitations)
|
||||
2. [Element Notification implementations](#element-notification-implementations)
|
||||
* [Requirements](#requirements)
|
||||
* [Foreground sync mode (Gplay & F-Droid)](#foreground-sync-mode-gplay--f-droid)
|
||||
* [Push (FCM) received in background](#push-fcm-received-in-background)
|
||||
* [FCM Fallback mode](#fcm-fallback-mode)
|
||||
* [F-Droid background Mode](#f-droid-background-mode)
|
||||
3. [Application Settings](#application-settings)
|
||||
|
||||
<!--- TOC -->
|
||||
<!--- END -->
|
||||
|
||||
|
||||
First let's start with some prerequisite knowledge
|
||||
|
||||
# Prerequisites Knowledge
|
||||
## Prerequisites Knowledge
|
||||
|
||||
## How does a matrix client get a message from a homeserver?
|
||||
### How does a matrix client get a message from a homeserver?
|
||||
|
||||
In order to get messages from a homeserver, a matrix client need to perform a ``sync`` operation.
|
||||
|
||||
|
|
@ -52,7 +40,7 @@ By default, this is 0, so the server will return immediately even if the respons
|
|||
|
||||
When the Element Android app is open (i.e in foreground state), the default timeout is 30 seconds, and delay is 0.
|
||||
|
||||
## How does a mobile app receives push notification
|
||||
### How does a mobile app receives push notification
|
||||
|
||||
Push notification is used as a way to wake up a mobile application when some important information is available and should be processed.
|
||||
|
||||
|
|
@ -69,7 +57,7 @@ De-Googlified devices need to rely on something else in order to stay up to date
|
|||
There some cases when devices with google services cannot use FCM (network infrastructure limitations -firewalls-,
|
||||
privacy and or independence requirement, source code licence)
|
||||
|
||||
## Push VS Notification
|
||||
### Push VS Notification
|
||||
|
||||
This need some disambiguation, because it is the source of common confusion:
|
||||
|
||||
|
|
@ -81,7 +69,7 @@ This need some disambiguation, because it is the source of common confusion:
|
|||
Notifications are not always triggered by a push (One can display a notification locally triggered by an alarm)
|
||||
|
||||
|
||||
## Push in the matrix federated world
|
||||
### Push in the matrix federated world
|
||||
|
||||
In order to send a push to a mobile, App developers need to have a server that will use the FCM APIs, and these APIs requires authentication!
|
||||
This server is called a **Push Gateway** in the matrix world
|
||||
|
|
@ -122,7 +110,7 @@ Recommended reading:
|
|||
* https://matrix.org/docs/spec/client_server/r0.4.0.html#id128
|
||||
|
||||
|
||||
## How does the homeserver know when to notify a client?
|
||||
### How does the homeserver know when to notify a client?
|
||||
|
||||
This is defined by [**push rules**](https://matrix.org/docs/spec/client_server/r0.4.0.html#push-rules-).
|
||||
|
||||
|
|
@ -140,14 +128,14 @@ Of course, content patterns matching cannot be used for encrypted messages serve
|
|||
|
||||
That is why clients are able to **process the push rules client side** to decide what kind of notification should be presented for a given event.
|
||||
|
||||
## Push vs privacy, and mitigation
|
||||
### Push vs privacy, and mitigation
|
||||
|
||||
As seen previously, App developers don't directly send a push to the end user's device, they use a Push Provider as intermediary. So technically this intermediary is able to read the content of what is sent.
|
||||
|
||||
App developers usually mitigate this by sending a `silent notification`, that is a notification with no identifiable data, or with an encrypted payload. When the push is received the app can then synchronise to it's server in order to generate a local notification.
|
||||
|
||||
|
||||
## Background processing limitations
|
||||
### Background processing limitations
|
||||
|
||||
A mobile applications process live in a managed word, meaning that its process can be limited (e.g no network access), stopped or killed at almost anytime by the Operating System.
|
||||
|
||||
|
|
@ -167,15 +155,15 @@ The documentation on this subject is vague, and as per our experiments not alway
|
|||
|
||||
It is getting more and more complex to have reliable notifications when FCM is not used.
|
||||
|
||||
# Element Notification implementations
|
||||
## Element Notification implementations
|
||||
|
||||
## Requirements
|
||||
### Requirements
|
||||
|
||||
Element Android must work with and without FCM.
|
||||
* The Element android app published on F-Droid do not rely on FCM (all related dependencies are not present)
|
||||
* The Element android app published on google play rely on FCM, with a fallback mode when FCM registration has failed (e.g outdated or missing Google Play Services)
|
||||
|
||||
## Foreground sync mode (Gplay & F-Droid)
|
||||
### Foreground sync mode (Gplay & F-Droid)
|
||||
|
||||
When in foreground, Element performs sync continuously with a timeout value set to 10 seconds (see HttpPooling).
|
||||
|
||||
|
|
@ -185,7 +173,7 @@ This mode is turned on when the app enters foreground, and off when enters backg
|
|||
|
||||
In background, and depending on whether push is available or not, Element will use different methods to perform the syncs (Workers / Alarms / Service)
|
||||
|
||||
## Push (FCM) received in background
|
||||
### Push (FCM) received in background
|
||||
|
||||
In order to enable Push, Element must first get a push token from the firebase SDK, then register a pusher with this token on the homeserver.
|
||||
|
||||
|
|
@ -225,7 +213,7 @@ Upon reception of the FCM push, Element will perform a sync call to the homeserv
|
|||
|
||||
Element implements several strategies in these cases (TODO document)
|
||||
|
||||
## FCM Fallback mode
|
||||
### FCM Fallback mode
|
||||
|
||||
It is possible that Element is not able to get a FCM push token.
|
||||
Common errors (among several others) that can cause that:
|
||||
|
|
@ -246,7 +234,7 @@ Usually in this mode, what happen is when you take back your phone in your hand,
|
|||
|
||||
The fallback mode is supposed to be a temporary state waiting for the user to fix issues for FCM, or for App Developers that has done a fork to correctly configure their FCM settings.
|
||||
|
||||
## F-Droid background Mode
|
||||
### F-Droid background Mode
|
||||
|
||||
The F-Droid Element flavor has no dependencies to FCM, therefore cannot relies on Push.
|
||||
|
||||
|
|
@ -266,9 +254,7 @@ That is why on Element F-Droid, the broadcast receiver will acquire a temporary
|
|||
|
||||
Note that foreground services require to put a notification informing the user that the app is doing something even if not launched).
|
||||
|
||||
|
||||
|
||||
# Application Settings
|
||||
## Application Settings
|
||||
|
||||
**Notifications > Enable notifications for this account**
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue