mirrors/element-android
1
0
Fork 0
mirror of https://github.com/element-hq/element-android synced 2024-11-23 18:05:36 +03:00
Code Issues Projects Releases Packages Wiki Activity

Setup knit TOC.

Browse source 
Only ## and more heading will be listed, so add a "h" level.
This commit is contained in:
Benoit Marty 2022-05-30 14:30:28 +02:00
parent 828e13f9be
commit b3a5812a61
1 changed files with 18 additions and 32 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

50
docs/notifications.md
View file

@ -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. 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 # 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) <!--- TOC -->
* [How does a mobile app receives push notification?](#how-does-a-mobile-app-receives-push-notification) <!--- END -->
* [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)
First let's start with some prerequisite knowledge 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. 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. 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. 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-, There some cases when devices with google services cannot use FCM (network infrastructure limitations -firewalls-,
privacy and or independence requirement, source code licence) 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: 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) 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! 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 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 * 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-). 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. 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. 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. 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. 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. 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. 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 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) * 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). 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) 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. 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) 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. It is possible that Element is not able to get a FCM push token.
Common errors (among several others) that can cause that: 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. 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. 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). 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** **Notifications > Enable notifications for this account**