Push notification support was added to the Echo extension in version 1.36.0. The implementation is documented here.
Push notification support is implemented as a third
push notifier type alongside the previously existing
push notifier, implemented in the
EchoPush\PushNotifier class, handles notifications by enqueuing an
EchoPushNotificationRequest job to query the DB for any registered push subscriptions associated with the recipient's global user ID. Push notification requests are sent to an external service (see mediawiki/services/push-notifications) for each subscription found. As currently implemented, the notification requests contain only a generic message intended to prompt the recipient app to "phone home" to the MediaWiki API's notifications module to retrieve full message content.
It is the client's responsibility to register users' push subscriptions via the echopushsubscriptions API module and update their notification preferences in order to benefit from push notifications.
As of September 2020, only app push notifications are supported, via Firebase Cloud Messaging (FCM) for Android and Apple Push Notification Service (APNS) for iOS. In the future (prospectively Q2 FY2020-2021) Echo will be updated to handle web push.
As of September 2020, Echo push is enabled on the Wikipedias only.
Config variables edit
$wgEchoEnablePush: Whether push functionality will be enabled. If false, the push notifier type, the
echopushsubscriptionsAPI module, and the push notification preferences column will be suppressed. (Default:
$wgEchoPushServiceBaseUrl: Base URL for the Echo push service. (Default:
$wgEchoPushMaxSubscriptionsPerUser: The maximum number of subscriptions that may be associated with a global user ID. (Default:
Subscription registration edit
Clients can create and delete subscriptions using the echopushsubscriptions API module. Subscriptions are associated with a user's global user ID. It is preferred that clients create subscriptions on login and delete them on logout. The maximum number of subscriptions per global user ID is defined in
$wgEchoPushMaxSubscriptionsPerUser. Currently (as of September 2020), the maximum at Wikimedia is 10. If a user subscribes more than the maximum number of tokens, the oldest previous token will be removed, so that the total number is still 10.
When the push service receives a response from a push provider API indicating that a token is invalid, it will make a request to the MediaWiki to delete the subscription associated with the token. This is not yet fully implemented; follow T260247 and subtasks for the current status of that work.
Updating notification preferences via API edit
User notification preferences are stored along with all other user preferences in the core user_properties table. This table is essentially a generic key-value store. Clients can manage user preferences stored in this table using the options API module. Notification preference keys are structured according to the convention
echo-subscriptions-<notifierType>-<eventCategory> and the possible values are
1 (true) and
0 (false). Notifier types include
push, and event category strings can be found in MediaWiki core and in the various extensions in which they are implemented.
As an example, the preference key name governing push notifications when the user is thanked for an edit would be
echo-subscriptions-push-edit-thank. Accordingly, to enable push notifications via API, a client could submit the following request:
Note: These preferences are wiki-specific.
Data model edit
The main data store for this feature is the push subscriptions table (
echo_push_subscriptions). The subscription data includes push provider IDs and (optional) APNS topic IDs which are normalized to
echo_push_topic, respectively. Echo interacts with these latter tables through the core NameTableStore (T216468) interface.
At Wikimedia, the
echo_push_* tables are hosted in the
wikishared database in the
extension1 (x1) cluster.
TODO: Document the current DB schema
Quirks and gotchas edit
LocalSettings.php or in
CommonSettings[-labs].php at Wikimedia. This is to support conditionally enabling push by wiki. As of September 2020, in Wikimedia production, Echo push is only enabled on the Wikipedias. If and when Echo push is rolled out to all Wikis, this configuration can be moved to extension.json.