mirror of
https://github.com/zulip/zulip.git
synced 2025-11-04 05:53:43 +00:00
docs: Improve Mobile push notification service documentation.
This commit is contained in:
Alya Abbott
Tim Abbott
@@ -1,94 +1,71 @@
|
||||
# Mobile push notification service
|
||||
|
||||
Zulip's iOS and Android mobile apps support receiving push
|
||||
notifications from Zulip servers to let users know when new messages
|
||||
have arrived. This is an important feature to having a great
|
||||
experience using the Zulip mobile apps.
|
||||
Zulip's iOS and Android [mobile apps](https://zulip.com/apps/) support receiving
|
||||
push notifications from Zulip servers to let users know when new messages have
|
||||
arrived. This is an important feature for having a great mobile app experience.
|
||||
|
||||
For technical reasons (explained below), in order to deliver mobile
|
||||
push notifications in the app store versions of our mobile apps, you
|
||||
will need to register your Zulip server with the Zulip mobile push
|
||||
notification service. This service will forward push notifications
|
||||
generated by your server to the Zulip mobile app automatically.
|
||||
To set up mobile push notifications, you will need to register your Zulip server
|
||||
with the Zulip mobile push notification service. This service will forward push
|
||||
notifications generated by your server to users' mobile apps.
|
||||
|
||||
## How to sign up
|
||||
|
||||
Starting with Zulip 1.6 for both Android and iOS, Zulip servers
|
||||
support forwarding push notifications to a central push notification
|
||||
forwarding service. Accessing this service requires outgoing HTTPS
|
||||
access to the public Internet; if that is restricted by a proxy, you
|
||||
will need to [configure Zulip to use your outgoing HTTP
|
||||
proxy](deployment.md#customizing-the-outgoing-http-proxy)
|
||||
You can enable the mobile push notification service for your Zulip server as
|
||||
follows:
|
||||
|
||||
1. Make sure your server has outgoing HTTPS access to the public Internet. If
|
||||
that is restricted by a proxy, you will need to [configure Zulip to use your
|
||||
outgoing HTTP proxy](deployment.md#customizing-the-outgoing-http-proxy)
|
||||
first.
|
||||
|
||||
You can enable this for your Zulip server as follows:
|
||||
1. Decide whether to upload basic usage statistics. Systems using the Mobile
|
||||
Push Notifications Service will, by default, submit basic usage statistics
|
||||
(e.g. Zulip version, number of users, number of messages sent) to the service.
|
||||
These statistics help Zulip's maintainers understand how many people are
|
||||
self-hosting Zulip in order to allocate resources towards supporting
|
||||
self-hosted installations.
|
||||
|
||||
Our use of these statistics is governed by the same [Terms of
|
||||
Service](https://zulip.com/policies/terms) and [Privacy
|
||||
Policy](https://zulip.com/policies/privacy) that covers the Mobile Push
|
||||
Notifications Service itself. If your organization does not want to submit these
|
||||
statistics, you can disable this feature during setup or at any time by setting
|
||||
`SUBMIT_USAGE_STATISTICS=False` in `/etc/zulip/settings.py`.
|
||||
|
||||
1. Uncomment the
|
||||
`PUSH_NOTIFICATION_BOUNCER_URL = 'https://push.zulipchat.com'` line
|
||||
in your `/etc/zulip/settings.py` file (i.e. remove the `#` at the
|
||||
in your `/etc/zulip/settings.py` file (i.e., remove the `#` at the
|
||||
start of the line), and [restart your Zulip
|
||||
server](settings.md#making-changes). If you
|
||||
installed your Zulip server with a version older than 1.6, you'll
|
||||
need to add the line (it won't be there to uncomment).
|
||||
server](settings.md#making-changes).
|
||||
|
||||
1. If you're running Zulip 1.8.1 or newer, you can run the
|
||||
registration command:
|
||||
1. Run the registration command. If you installed Zulip directly on the server
|
||||
(without Docker), run as root:
|
||||
|
||||
```bash
|
||||
# As root:
|
||||
```
|
||||
su zulip -c '/home/zulip/deployments/current/manage.py register_server'
|
||||
# Or as the zulip user, you can skip the `su zulip -c`:
|
||||
/home/zulip/deployments/current/manage.py register_server
|
||||
```
|
||||
|
||||
# docker-zulip users can run this inside the container with `docker exec`:
|
||||
Or if you're using Docker, run:
|
||||
|
||||
```
|
||||
docker exec -it -u zulip <container_name> /home/zulip/deployments/current/manage.py register_server
|
||||
```
|
||||
|
||||
This command will print the registration data it would send to the
|
||||
mobile push notifications service, ask you to accept the terms of
|
||||
service, and if you accept, register your server. If you have trouble,
|
||||
email support@zulip.com with the output of this command.
|
||||
This command will print the registration data it would send to the mobile
|
||||
push notifications service, ask you to accept the terms of service, and if
|
||||
you accept, register your server. If you have trouble, [contact Zulip
|
||||
support](https://zulip.com/help/contact-support) with the output of this
|
||||
command.
|
||||
|
||||
1. If you or your users have already set up the Zulip mobile app,
|
||||
you'll each need to log out and log back in again in order to start
|
||||
1. If you or your users have already set up the Zulip mobile app, you'll each
|
||||
need to log out of the mobile app, and log back in again in order to start
|
||||
getting push notifications.
|
||||
|
||||
Congratulations! You've successfully set up the service.
|
||||
Congratulations! You've successfully set up the service. You can now test mobile
|
||||
push notifications by following [these
|
||||
instructions](https://zulip.com/help/mobile-notifications#testing-mobile-notifications).
|
||||
|
||||
If you'd like to verify that everything is working, you can do the
|
||||
following. Please follow the instructions carefully:
|
||||
|
||||
- [Configure mobile push notifications to always be sent][mobile-notifications-always]
|
||||
(normally they're only sent if you're idle, which isn't ideal for
|
||||
this sort of testing).
|
||||
- On an Android device, download and log in to the
|
||||
[Zulip Android app](https://play.google.com/store/apps/details?id=com.zulipmobile).
|
||||
If you were already logged in before configuring the server, you'll
|
||||
need to log out first, since the app only registers for push
|
||||
notifications on login.
|
||||
- Hit the home button, so Zulip is running in the background, and then
|
||||
have **another user** send you a **direct message** (By default,
|
||||
Zulip only sends push notifications for direct messages sent by other
|
||||
users and messages mentioning you). A push notification should appear
|
||||
in the Android notification area.
|
||||
|
||||
[mobile-notifications-always]: https://zulip.com/help/test-mobile-notifications
|
||||
|
||||
## Updating your server's registration
|
||||
|
||||
Your server's registration includes the server's hostname and contact
|
||||
email address (from `EXTERNAL_HOST` and `ZULIP_ADMINISTRATOR` in
|
||||
`/etc/zulip/settings.py`, aka the `--hostname` and `--email` options
|
||||
in the installer). You can update your server's registration data by
|
||||
running `manage.py register_server` again.
|
||||
|
||||
If you'd like to rotate your server's API key for this service
|
||||
(`zulip_org_key`), you need to use
|
||||
`manage.py register_server --rotate-key` option; it will automatically
|
||||
generate a new `zulip_org_key` and store that new key in
|
||||
`/etc/zulip/zulip-secrets.conf`.
|
||||
|
||||
## Why this is necessary
|
||||
## Why a push notification service is necessary
|
||||
|
||||
Both Google's and Apple's push notification services have a security
|
||||
model that does not support mutually untrusted self-hosted servers
|
||||
@@ -160,24 +137,8 @@ and privacy in mind:
|
||||
- The push notification forwarding servers are professionally managed
|
||||
by a small team of security expert engineers.
|
||||
|
||||
If you have any questions about the security model, contact
|
||||
support@zulip.com.
|
||||
|
||||
## Submitting statistics
|
||||
|
||||
Systems using the Mobile Push Notifications Service will, by default,
|
||||
submit basic usage statistics (e.g. Zulip version, number of users,
|
||||
number of messages sent) to the service. These statistics help the
|
||||
Zulip open source project understand how many people are using Zulip,
|
||||
and help us allocate resources towards supporting self-hosted
|
||||
installations.
|
||||
|
||||
Our use of these statistics is governed by the same [Terms of
|
||||
Service](https://zulip.com/policies/terms) and [Privacy
|
||||
Policy](https://zulip.com/policies/privacy) that covers the Mobile Push
|
||||
Notifications Service itself. If your organization does not want to submit these
|
||||
statistics, you can disable this feature at any time by setting
|
||||
`SUBMIT_USAGE_STATISTICS=False` in `/etc/zulip/settings.py`.
|
||||
If you have any questions about the security model, [contact Zulip
|
||||
support](https://zulip.com/help/contact-support).
|
||||
|
||||
## Rate limits
|
||||
|
||||
@@ -193,6 +154,20 @@ anticipate that your server will require sending more push
|
||||
notifications than the limit permits, please [contact
|
||||
support](https://zulip.com/help/contact-support).
|
||||
|
||||
## Updating your server's registration
|
||||
|
||||
Your server's registration includes the server's hostname and contact
|
||||
email address (from `EXTERNAL_HOST` and `ZULIP_ADMINISTRATOR` in
|
||||
`/etc/zulip/settings.py`, aka the `--hostname` and `--email` options
|
||||
in the installer). You can update your server's registration data by
|
||||
running `manage.py register_server` again.
|
||||
|
||||
If you'd like to rotate your server's API key for this service
|
||||
(`zulip_org_key`), you need to use
|
||||
`manage.py register_server --rotate-key` option; it will automatically
|
||||
generate a new `zulip_org_key` and store that new key in
|
||||
`/etc/zulip/zulip-secrets.conf`.
|
||||
|
||||
## Sending push notifications directly from your server
|
||||
|
||||
This section documents an alternative way to send push notifications
|
||||
@@ -205,25 +180,22 @@ mobile app can take dozens of hours to set up even for an experienced
|
||||
developer, and even more time to maintain. And it doesn't provide
|
||||
material privacy benefits -- your organization's push notification
|
||||
data would still go through Apple/Google's servers, just not Kandra
|
||||
Labs'. Our view is the correct way to optimize for privacy is
|
||||
end-to-end encryption of push notifications. But in the interest of
|
||||
transparency, we document in this section roughly what's involved in
|
||||
doing so.
|
||||
Labs'. But in the interest of transparency, we document in this
|
||||
section roughly what's involved in doing so.
|
||||
|
||||
As we discussed above, it is impossible for a single app in their
|
||||
stores to receive push notifications from multiple, mutually
|
||||
As [discussed above](#why-a-push-notification-service-is-necessary),
|
||||
it is impossible for a single app in the Google or Apple
|
||||
store to receive push notifications from multiple, mutually
|
||||
untrusted, servers. The Mobile Push Notification Service is one of
|
||||
the possible solutions to this problem. The other possible solution
|
||||
is for an individual Zulip server's administrators to build and
|
||||
distribute their own copy of the Zulip mobile apps, hardcoding a key
|
||||
that they possess.
|
||||
the possible solutions to this problem.
|
||||
|
||||
This solution is possible with Zulip, but it requires the server
|
||||
administrators to publish their own copies of
|
||||
the Zulip mobile apps (and there's nothing the Zulip team can do to
|
||||
eliminate this onerous requirement).
|
||||
The other possible solution is for an individual Zulip server's administrators
|
||||
to build and distribute their own copy of the Zulip mobile apps, hardcoding a
|
||||
key that they possess. This solution is possible with Zulip, but it requires the
|
||||
server administrators to publish their own copies of the Zulip mobile apps.
|
||||
There's nothing the Zulip team can do to eliminate this onerous requirement.
|
||||
|
||||
The main work is distributing your own copies of the Zulip mobile apps
|
||||
The main work is thus distributing your own copies of the Zulip mobile apps
|
||||
configured to use APNS/FCM keys that you generate. This is not for
|
||||
the faint of heart! If you haven't done this before, be warned that
|
||||
one can easily spend hundreds of dollars (on things like a DUNS number
|
||||
|
||||
Reference in New Issue
Block a user