Requirements Document

👋

Contributors List

Whether you’re observing this project, or are planning on actively contributing, please share contact details in the following sheet so everyone knows whos’ involved.

View Contributors List Doc

For updates, follow the #feature-notifications tag on the on Make WordPress Core blog.

For discussion, join #feature-notifications on Slack.

For notes and updates, you can view the Office Hours notes

Table of Contents

[TOC]

1. Objectives

Create a new (better) way to manage and deliver notifications to the relevant audience.

1. Allow WordPress core to send notifications to administrative users to give them feedback about changes in the system.
2. Allow plugin and theme authors to send notifications to administrative users to give them feedback about changes in the system
3. Prevent plugin and theme authors from abusing this notification system in “spammy” ways.
4. Allow WordPress users who have access to notifications to control which, how, and where they receive them.

2. Use Cases

1. Action required: the plugin wants the user to take a decision, i.e. “you got a comment” (action, notification)
2. Onboarding: the plugin wants to provide guidance on a specific feature, i.e. “try this feature” (action, on-page)
3. Informative: the plugin wants to inform the user about something, i.e. “backup completed” (no action, notification)
4. State: the plugin changes its state, i.e. “settings saved” (no action, on-page)
5. Marketing: the plugin wants to advertise something or suggest an upgrade, i.e. “buy an upgrade!” (action, on-page)

2.1. Terminology

1. Action
   • a single button or some form of tappable/clickable interaction for the user to do
2. Notification
   • a notification hub, with maybe a dropdown or a container of some sort, that shows alerts across pages
3. On Page
   • a local notification, shown only on a specific page, and contextual to the page content

3. Current Status

WordPress is currently lacking a fundamental mechanism: sending notifications to users to give them feedback about state changes in the system. Traditionally, WordPress core and theme/plugin developers have been using the admin_notices hook for this purpose, but this solution is lackluster at best and comes with a lot of disadvantages. So we need a more robust replacement that can deal with current and future notification needs.

Note that given the nature and needs of the different themes and plugins, this also creates three additional issues:

1. Long-term admin notices that stay visible until the user takes some action, i.e. if the plugin needs configuration, the notice will be visible until the configuration is done.
2. Short-term admin notices that simply give short-term alerts.
3. “Marketing” style notices, that appear to have hijacked the WordPress dashboard, and cause confusion for the user

3.1. Current Implementation

Currently, WP has only one kind of notifications workflow: admin notices which hook into the rendering of the WP admin page creation process, to display a message in HTML.

1. No data is saved per notice created.
2. No priority discrimination is assigned to each notice queued for rendering.
3. No email handling is done for notices.
4. No standard is applied to filter notices based on the user's capabilities.
5. No standard way to manage state of a notice. (The most common workaround is using transients).
6. No standard is followed or enforced regarding how a notice should appear.

3.2. Current limitations

1. Notifications are rendered into the normal working area in the dashboard and can even push the actual page content below the fold.
2. The user has no control over how or when they deal with notifications, therefore they see them in a mostly negative fashion.
3. They are nothing more than printed HTML. Because they lack any kind of structure, it is not possible to manipulate them in an automated fashion, or view them in a historical and priority-flagged method.
4. Their persistence is not regulated, which leads to many different implementations as well as cruft in the database.

4. Project Goal

This goal of this project is to provide a less cluttered way to experience, manage, and deliver notifications to the relevant audience. It will fulfill the use cases detailed above.

4.1. Intended Audience

Backend Users

Any and all users of the WordPress admin dashboard and its views, with different levels of access, and the need to configure the kind of notification they receive.

Site Admins

User with maintenance and advanced capabilities to the site, required to deal with setup functionalities that normal users won’t see.

Plugin Authors

Developers who create WordPress plugins that generate notifications to users (in some capacity and priority).

Theme Authors

Developers who create WordPress themes. These themes require some form of setup to happen before it can be used safely, or require usage instructions.

4.2. Scope (for v.1)

While we are working to a longer term view of a fully implemented notification system, the scope for the v1 will be shorter, an MVP, in order to put the pieces in place, deliver value early, and iterate with feedback.

Research

1. Categorize, identify and prioritize all the existing uses of admin notices, based on real examples (i.e. review top X plugins and themes, interview developers).
2. Benchmark existing plugins, APIs, and notification patterns inside and outside the WordPress ecosystem to make sure we are providing something that is best in class (even in its initial basic form) and they can build upon too.
3. Review past recommendations of solutions for notifications, and look ahead at what practices/methods are trending related to notifications.
4. Research the Gutenberg notifications method
5. Research method for background handling of notices (cron job) [link]

Frontend (WP Admin Area)

1. A settings page that lets the user control which notifications to show/hide in the admin bar and which notifications to forward through email.
2. For “notification-type” messages:
   1. An admin bar integration that shows notification state.
   2. A hub that shows all notification-type messages chronologically.
3. For “on-page-type” messages 3. A reserved space on the page used to show the message itself.
4. All the above, dependent on user role/capability.

Backend (Code level)

1. Backwards compatibility handler for existing non-core admin notices (i.e. plugin or themes using admin_notices)
2. An object model that is extensible as well as serializable (to JSON).
3. A persistence abstraction that comes with an initial WPDB implementation.
4. A queuing system that allows for processing notifications to distribute them across channels, for use cases where this is a costly operation, like sending them through email.
5. Plugins can specify capabilities so only the users that can perform a specific action will see the matching notification.
6. A simplified procedural API that allows for easy manipulations the way plugin developers are accustomed to.
7. Any message content will be translation ready
8. REST API controllers that provide endpoints to manage the notification from the frontend, and allows access from the mobile app.

5. System Features and Requirements

5.1. Functional Requirements

1. Objects must be serializable to JSON in such a way that it can be sent to the client, either as a localized JavaScript snippet or as a REST API response.
2. A notification can have one or more recipients, which can be users, roles or a mixture of both.
3. It should be possible for a single recipient to mark a notification as read, but it is still presented to the rest of the recipients, as described above.
4. A recipient can configure the channel(s) they want to receive the notifications in, on a “per-group” basis.
5. Distribution across channels is not directly coupled to the frontend request, but works as a background queue.
6. The admin bar integration needs to build on top of the work done with Gutenberg and use a reactive interface powered by the REST API.
7. Provide a hook when the message is closed and update the read status, so the plugins can use that information.

5.4. Nonfunctional Requirements

1. Accessible from anywhere.
2. Follow good real-world accessibility (a11y) practices.
3. End users have full control over notifications delivery, and frequency, with good defaults to start with.
4. One location for all notification-type messages.

5.2. External Interface Requirements

1. WP Mail handling (queuing) of notifications
2. Cron processing of notifications

5.3. PHP API for Plugin Integrations

1. Wrapper functions as a top level layer for developers accustomed with WordPress procedural style of code
2. Action and filters to hook on
3. A lower level, but still extendable OOP API for developers with a need to add features to the current system

5.4. REST API for Mobile Integrations

1. The API should provide a way for the WordPress (and other third-party) mobile apps (iOS, Android, …) to integrate.
2. CRUD Rest API methods (XML-RPC until auth becomes available on the REST API)
   1. This may not be necessary, as core may ship some additional form of REST API authentication later this (2020) year, so it may be moot by the time this system actually gets built.
3. accessible to mobile apps to interact with Notifications.

6. Delivery

Proposed ways to deliver this solution:

• Feature-Plugin (to later be merged into core)
• Composer Package

Appendix A: Further Sources

This list contains all contributions that people might have written somewhere, for example a blog post or a talk, that is informative and part of the history that can be reviewed to make this document.

• L. Carbis (2019) WP Notify
• A. Schlesser (2018) Feature Project Proposal draft (posted later on Make)
• A. Schlesser (2018) Ticket 43484 comment with technical notes

Appendix B: Glossary

• API: application programming interface, in this case defines both the internal set of functions and hooks plugins can use to use the notification system, and the external set of endpoints (REST API) to interface from the outside (i.e. mobile)
• Message: any informative textual message sent to a user
• Notice, Notification: we use them interchangeably, they are a type of message that is shown on top of existing pages, not directly related to the page they are on, and might be aggregated together in a list or hub. This is similar to Facebook notifications, iOS/Android notifications, and so on.
• On-Page: a type of message that is shown on the page itself, and is directly related to the page it’s shown on.
• User: for the context of this project, any person interacting with WordPress Admin, regardless of their level of access as long as they can see the Admin interface (i.e. not external users).
• User Capability: a capability is permission to perform one or more types of task.
• User Role: a role defines a set of tasks a user assigned the role is allowed to perform. Roles can be: super admin, admin, editor, contributor, subscriber. Each role is allowed to do multiple Capabilities (see).
• Screen, View: a single page taking over the entire browser view.

Appendix C: Possible solutions/tools

• Gutenberg Snackbar implementation
  • https://github.com/WordPress/gutenberg/blob/master/packages/components/src/snackbar/README.md

Appendix D: Dependencies

1. TBD

Appendix E: Possible Single notification requirements:

This discussion came out of the requirements gathering process, however this would probably be better detailed as part of the final technical specification.

1. A text field or title text field combination, but with a limited set of characters. It is preferable that one notification is not allowed to to get so long that it fills up the whole visible sidebar.
2. The ability to add an action link (view upgrade/trigger action etc)
3. The ability to add a dismiss link.
4. A type (ie core admin notice, plugin/theme admin notice, other)
5. A timestamp.
6. An icon or image. Could be the plugin icon, author avatar, or something like a category/message type, like info, warning, question, error, update, to visually distinguish notifications quickly.
7. A status, meaning read or unread.
8. A notification should be able to change over the time (change in content, priority, folding, unfolding, etc). Even if the API won’t be available from v1, we need to make sure to not constrain the internals and allow for this to happen later.
9. One call to action (and a second to dismiss, provided by default)

Appendix F: Possible v2 updates

This section gathers all comments from parties that are aimed at a future release.

I believe that an option to "mute" specific plugins could also be usefull. This could either be a permanent mute or until the plugin's next update (in case they indeed need to announce something actually important) and it should of course be disabled by default.I've posted this suggestion in a few more details here: https://wordpress.org/ideas/topic/mute-plugin-notifications for anyone interested

Have you thought about a Service Worker implementation for Push Notifications as well? The biggest limitation here would be that Safari doesn't support Service Workers yet, but I have been able to create a Service worker that would send push notifications when a certain hook is fired from WordPress using Javascript.

External log handling - when running/administrating more than one instance the notifications should be clustered. A possibility to push them to something like GrayLog, ELK-Stack etc. would be helpful besides the notifications in WP and/or email notifications