Page MenuHomePhabricator

[Spike]: Notification content
Open, MediumPublicSpike


This spike is for engineers to answer questions we have around the notification content display:

Question 1

What information do we get from notifications API on each notification?

Answer: This is not comprehensive, but I made a spreadsheet of many notifications that I was able to trigger and their structure, located here:

Any additional or future notifications we can handle in a generic way as a part of

Question 2

What do we need to fetch to fill out the content view in both the standard notification, the deep press rich content system notification and content in the app notification center, as well as quick actions for each notification type? (notifications API is here)

Answer: Much of this we can do with the standard notification response objects without any additional data. I will highlight the stuff that will be more difficult:

  • Some section names - Some talk page and mention notification objects return a primary url with the section name as the fragment. We just have to extract that and remove the underscores, so this can be done. There may be other notification types (like flow) that do not have this data, so we should provide a fallback option without the section name if this happens.
  • Indicating that a reply was to your message ("USERNAME responded to your message on TALK PAGE TITLE [in the section SECTION NAME]") - We will be able to tell if a new topic or reply is on the recipient's talk page, so we can use the phrase "your talk page". But we can't tease apart that someone specifically replied to the recipient's message on a different talk page. So this would just need to be "USERNAME replied in TALK PAGE TITLE".
  • Indicating a reply on classic talk pages ("Reply from [Username]") - The data for a new topic and a reply look the same, so we won't be able to differentiate this with the copy we show.
  • Inline replying in notification center or OS quick action - Unfortunately we don't receive a section ID on classic talk page messages, so we can't easily post an inline reply. It will be a little easier for flow, but we still need to parse through the url for the topic identifier. I suggest we nix or wait to see how Android does it.
  • Indicating number of failed login attempts in a custom message - We can either use the full message that API response gives us (we will strip html) "There have been <b>5 failed attempts</b> to log in to your account since the last time you logged in. If it wasn't you, please make sure your account has a strong password.", or something generic "There have been failed attempts to log in.". We can't both shorten this text AND indicate number ("There have been 5 failed attempts to log in."). This is because we don't get a distinct failed number as a separate piece of data.
  • Page summary preview on thank, edit reverted and mention notifications - We can likely add a page summary in the rich notification view (still extra work, but not too bad), but it would be very difficult to add it to the app notification center cells because that data comes from a separate fetch. If you don't mind them being different we can only show it in the rich notification view and remove from the notification center view, or nix both.
  • Edit summary in Edit reverted, talk page mentions - similar to page summary above, we can do this (with work) within the rich notification view, but not in the app notification center view.
  • Login notify (new device) - I haven't been able to trigger this one, so just mentioning here that I don't have enough info to advise yet.

Question 3

What formatting can we support in standard OS notifications and rich OS notifications? Can we support blue links in rich notifications? If on two separate lines (and vertically adjacent), is the tap target too difficult for users to hit?


  • We can't intersperse bold text or links in the standard OS notification view (the non-rich one). We have a Title, Subtitle, and Body text to work with. Title and Subtitle are on their own lines and bold.
  • We can intersperse bold text and blue links in rich notifications. Unsure about tap targets, but we can easily nix if they become too difficult.

Question 4

Will we be able to tease out particular links (like the username or article title) from the API response for some of these notifications?

Answer: It depends. We get user information (in agent object) and article information (in title object) for notifications. So with that plus the notification type means we can construct almost any copy we want for recognized notifications. But one big caveat is we would then be relying on local translations to trickle in for any custom copy we construct. The alternative would be to use the text the Notifications API already gives us (which I think is what is displayed on Desktop), and will likely arrive to us already translated. The downside to that is we will have less freedom in the copy we use and how we format it.

Followup: We discussed this in planning, see notes here:

Additional spike discoveries and sidenotes

  • The agent can be anonymous on many of these notifications. We'll need copy and quick actions for anonymous users. ("An anonymous user left a message on your talk page", hide "go to [anonymous user's] talkpage" option, etc.).
  • We can ask the API to bundle up the notifications for us using the notbundle=1 flag, but the structure looks painful to keep track of to me. I think it would be simpler for us to keep them all separate and coalesce the copy ourselves in the Notification Service Extension (app notification center will always show them broken out).
  • A nice surprise is that we do get some additional inline data as a part of the "body" fields. These are:
  1. We get the edit summary content for the thanks and mention (in edit summary) notification types
  2. We get the content of the edit for all of the new topic and reply notification types. If it's a new topic, we only get the body content, not the new topic subject/section name.
  3. We get the content of the talk page edit that a user was mentioned in, for the mention (in talk page) notification type.

Event Timeline

Tsevener created this task.
Tsevener edited projects, added Spike; removed Epic.
Restricted Application changed the subtype of this task from "Task" to "Spike". · View Herald TranscriptJun 3 2021, 4:30 PM
Tsevener updated the task description. (Show Details)
Tsevener updated the task description. (Show Details)

@cmadeo Updated the description with the answers for the spikes in this area. It is a big knowledge dump that was a little difficult to organize, so I'm happy to answer any follow up questions you may have! The very last list shows the inline data we get directly from the API that I mentioned earlier this week.

Macro peanut: Thank you!

@Tsevener thank you SO MUCH for this detailed breakdown (and super helpful spreadsheet!) I'm going to go ahead and make changes to the lock screen and system notification center notifications with these notes in mind.

I am curious if these limitations will also need to be applied to the in-appnotification center? Thanks!

@cmadeo yep, they apply to the in-app notification center too. The only place where these limitations differ based on placement is these:

We can do this UI on the rich system notification view but not the plain system notification view (i.e. lock screen, system notification center, not or deep/long pressing) nor the in-app notification center:

  • Page summary preview on thank, edit reverted and mention notifications
  • Edit summary in Edit reverted, talk page mentions

And the plain system notification view is limited in it's formatting. We can't intersperse bold text. We have a title, subtitle (both of which are bold) and body text (not bold) to work with on those.

Thanks for the clarification @Tsevener, so does this mean that the reorganizing or notification content to 1) pull out the thread as a subject line; 2) the username of the message center and; 3) the associated page where the notification occurred will be out of scope?

Notification center - No filters applied - Messages.png (812×375 px, 51 KB)

@Tsevener when you have the time, would you mind reviewing this Figma ( The 'page' should read 'Lock Screen Notifications v2...' I believe I was able to address all of the results of the spike in the lock screen and rich notifications, but please do let me know if I missed anything. Also happy to do this via a call instead!


so does this mean that the reorganizing or notification content to 1) pull out the thread as a subject line; 2) the username of the message center and; 3) the associated page where the notification occurred will be out of scope?

Actually only 1) is out of scope, we can pull the username and associated page from the API easily, especially since it looks like you're using them as separate UI elements in the in-app center. The only blocker I have is the Question 4 answer above, which applies to when you need to take that username and page and construct a single notification content sentence with it. We can talk about it in grooming today, might be easier if I discussed in person.

Update: Even 1 is doable, it looks like the primary url returned from the API returns a fragment with the thread title. We just have to extract that and remove the underscores.

Updating with what we discussed in planning today:

It is preferable to use the web sentence that comes back from the server (see the header value in the code sample below) for any notification sentence that we need to display in an OS notification or in the app center cells. We would take a translations hit if we reshuffled the sentence around. The API already gives us the web sentence translated, so if we reshuffled the sentence we would need to wait for translatewiki translations to come in for the new sentence. We also do know, from separate data, the username that triggered it, and the page title, so if we needed to we could seek out those elements from the web sentence and format them (bold, different color, etc, for rich OS notification view and in-app center view).

If the web sentence returned from the API is worded particularly poorly, it is fine for us to reword it and take the translations hit.

We can definitely display any UI element where the username or page title is on it's own, since we get that data separately. It is only when we're constructing our own custom sentences that we have this extra translation hit consideration.

@cmadeo is going to update mocks to the web version for any sentences that we can use. If any are worded poorly she will use custom copy.

Code sample shared in planning:

"wiki": "enwiki"
"id": 12345
"type": "mention-summary"
"category": "mention"
"agent": {
	"id": 56789
	"name": "TSevener (WMF)"
"title": {
	"full": "Cat",
	"namespace": "Main"
	"namespace-key": 0
	"text": "Cat"
"*": {
	"header": "TSevener (WMF) mentioned you in an edit summary on Cat."

Arbitrary UI example:
We would need to wait for translatewiki translations if we needed to display "You've been mentioned in an edit summary by TSevener (WMF) on Cat" somewhere. We would not need translatewiki if we used the "header" value directly.