mirror of
https://github.com/zulip/zulip.git
synced 2025-11-05 22:43:42 +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
|
# Mobile push notification service
|
||||||
|
|
||||||
Zulip's iOS and Android mobile apps support receiving push
|
Zulip's iOS and Android [mobile apps](https://zulip.com/apps/) support receiving
|
||||||
notifications from Zulip servers to let users know when new messages
|
push notifications from Zulip servers to let users know when new messages have
|
||||||
have arrived. This is an important feature to having a great
|
arrived. This is an important feature for having a great mobile app experience.
|
||||||
experience using the Zulip mobile apps.
|
|
||||||
|
|
||||||
For technical reasons (explained below), in order to deliver mobile
|
To set up mobile push notifications, you will need to register your Zulip server
|
||||||
push notifications in the app store versions of our mobile apps, you
|
with the Zulip mobile push notification service. This service will forward push
|
||||||
will need to register your Zulip server with the Zulip mobile push
|
notifications generated by your server to users' mobile apps.
|
||||||
notification service. This service will forward push notifications
|
|
||||||
generated by your server to the Zulip mobile app automatically.
|
|
||||||
|
|
||||||
## How to sign up
|
## How to sign up
|
||||||
|
|
||||||
Starting with Zulip 1.6 for both Android and iOS, Zulip servers
|
You can enable the mobile push notification service for your Zulip server as
|
||||||
support forwarding push notifications to a central push notification
|
follows:
|
||||||
forwarding service. Accessing this service requires outgoing HTTPS
|
|
||||||
access to the public Internet; if that is restricted by a proxy, you
|
1. Make sure your server has outgoing HTTPS access to the public Internet. If
|
||||||
will need to [configure Zulip to use your outgoing HTTP
|
that is restricted by a proxy, you will need to [configure Zulip to use your
|
||||||
proxy](deployment.md#customizing-the-outgoing-http-proxy)
|
outgoing HTTP proxy](deployment.md#customizing-the-outgoing-http-proxy)
|
||||||
first.
|
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
|
1. Uncomment the
|
||||||
`PUSH_NOTIFICATION_BOUNCER_URL = 'https://push.zulipchat.com'` line
|
`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
|
start of the line), and [restart your Zulip
|
||||||
server](settings.md#making-changes). If you
|
server](settings.md#making-changes).
|
||||||
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).
|
|
||||||
|
|
||||||
1. If you're running Zulip 1.8.1 or newer, you can run the
|
1. Run the registration command. If you installed Zulip directly on the server
|
||||||
registration command:
|
(without Docker), run as root:
|
||||||
|
|
||||||
```bash
|
```
|
||||||
# As root:
|
|
||||||
su zulip -c '/home/zulip/deployments/current/manage.py register_server'
|
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
|
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
|
This command will print the registration data it would send to the mobile
|
||||||
mobile push notifications service, ask you to accept the terms of
|
push notifications service, ask you to accept the terms of service, and if
|
||||||
service, and if you accept, register your server. If you have trouble,
|
you accept, register your server. If you have trouble, [contact Zulip
|
||||||
email support@zulip.com with the output of this command.
|
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,
|
1. If you or your users have already set up the Zulip mobile app, you'll each
|
||||||
you'll each need to log out and log back in again in order to start
|
need to log out of the mobile app, and log back in again in order to start
|
||||||
getting push notifications.
|
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
|
## Why a push notification service is necessary
|
||||||
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
|
|
||||||
|
|
||||||
Both Google's and Apple's push notification services have a security
|
Both Google's and Apple's push notification services have a security
|
||||||
model that does not support mutually untrusted self-hosted servers
|
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
|
- The push notification forwarding servers are professionally managed
|
||||||
by a small team of security expert engineers.
|
by a small team of security expert engineers.
|
||||||
|
|
||||||
If you have any questions about the security model, contact
|
If you have any questions about the security model, [contact Zulip
|
||||||
support@zulip.com.
|
support](https://zulip.com/help/contact-support).
|
||||||
|
|
||||||
## 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`.
|
|
||||||
|
|
||||||
## Rate limits
|
## Rate limits
|
||||||
|
|
||||||
@@ -193,6 +154,20 @@ anticipate that your server will require sending more push
|
|||||||
notifications than the limit permits, please [contact
|
notifications than the limit permits, please [contact
|
||||||
support](https://zulip.com/help/contact-support).
|
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
|
## Sending push notifications directly from your server
|
||||||
|
|
||||||
This section documents an alternative way to send push notifications
|
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
|
developer, and even more time to maintain. And it doesn't provide
|
||||||
material privacy benefits -- your organization's push notification
|
material privacy benefits -- your organization's push notification
|
||||||
data would still go through Apple/Google's servers, just not Kandra
|
data would still go through Apple/Google's servers, just not Kandra
|
||||||
Labs'. Our view is the correct way to optimize for privacy is
|
Labs'. But in the interest of transparency, we document in this
|
||||||
end-to-end encryption of push notifications. But in the interest of
|
section roughly what's involved in doing so.
|
||||||
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
|
As [discussed above](#why-a-push-notification-service-is-necessary),
|
||||||
stores to receive push notifications from multiple, mutually
|
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
|
untrusted, servers. The Mobile Push Notification Service is one of
|
||||||
the possible solutions to this problem. The other possible solution
|
the possible solutions to this problem.
|
||||||
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
|
The other possible solution is for an individual Zulip server's administrators
|
||||||
administrators to publish their own copies of
|
to build and distribute their own copy of the Zulip mobile apps, hardcoding a
|
||||||
the Zulip mobile apps (and there's nothing the Zulip team can do to
|
key that they possess. This solution is possible with Zulip, but it requires the
|
||||||
eliminate this onerous requirement).
|
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
|
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
|
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
|
one can easily spend hundreds of dollars (on things like a DUNS number
|
||||||
|
|||||||
Reference in New Issue
Block a user