Page MenuHomePhabricator

"Default" notification handling on iOS
Open, MediumPublic

Description

Why are we doing this?

We want to ensure that we have a way of handling notifications that are new or are outside of the current scope of the project.

Relevant links

https://www.mediawiki.org/wiki/Notifications/Design_guide
https://www.mediawiki.org/wiki/Help:Notifications/Document_a_new_notification_type
https://www.mediawiki.org/wiki/Extension:Echo/Creating_a_new_notification_type
https://www.mediawiki.org/wiki/Notifications/Developer_guide

Required fields
  • Project: Associated project (Wiki, Commons, etc)
  • ID: ???
  • Type: The name of the event, the key we used to define the event by adding it to &$notifications in the BeforeCreateEchoEvent hook
  • Category: The category this event belongs to. This is important for displaying in the Special:Preferences page
  • Section: Defines the section this notification belongs to. There are two types, Alerts and Notices. Alerts are for urgent notifications that should be dealt with promptly, e.g. a post on the user's talk page. Notices are for notifications that do not have to be dealt with promptly, e.g. a thank. For Alerts, put 'alert'. For Notices, put 'message'
  • Timestamp: The timestamp reflects the time the notification was generated.
  • Header: Primary message content (eg. Username replied in "Topicname")
  • Primary link (not always guaranteed): Main link related to the notification
Questions
  • What is ID? How does 'ID' manifest in a currently available notification?
  • Are icons determined by category or type?

Proposed designs
Lock screenLong pressIn-app notification
Lock screen notifications_ Generic notification.png (812×375 px, 378 KB)
Long press_ Generic notification.png (812×375 px, 208 KB)
Notification center - No data notification.png (812×375 px, 25 KB)
ElementSuggestionFall back
Icon + icon colorUse icon and color associated with [TYPE] or [CATEGORY]Blue background with SF symbols 'bell.fill' in the theme's 'paper' hex
First line of notification[NAME]Alert from [PROJECT
Second line of notification[HEADER]None
Blue link belowSF symbol 'link' + [PRIMARY LINK]Leave blank (do not show an associated icon)
Dependencies

https://phabricator.wikimedia.org/T287310
https://phabricator.wikimedia.org/T288662
https://phabricator.wikimedia.org/T288670
https://phabricator.wikimedia.org/T288687
https://phabricator.wikimedia.org/T288658

Event Timeline

@cmadeo

Here is an example of a typical notification (this one is a classic talk page reply):

{
	"wiki": "enwiki",
	"id": 223017027,
	"type": "edit-user-talk",
	"category": "edit-user-talk",
	"section": "alert",
	"timestamp": {
		"utciso8601": "2021-07-16T22:57:03Z",
		"utcunix": 1626476223,
		"unix": "1626476223",
		"utcmw": "20210716225703",
		"mw": "20210716225703",
		"date": "Today"
	},
	"title": {
		"full": "User talk:TSevener (WMF)",
		"namespace": "User_talk",
		"namespace-key": 3,
		"text": "TSevener (WMF)"
	},
	"agent": {
		"id": 35425575,
		"name": "Tsevener"
	},
	"revid": 1033965765,
	"read": "20210716225725",
	"targetpages": [],
	"*": {
		"header": "\u202aTsevener\u202c left a message on <strong>your talk page</strong> in \"<strong>\u202aTesting new section notification for spike again\u202c</strong>\".",
		"compactHeader": "\u202aTsevener\u202c left you a message in \"<strong>\u202aTesting new section notification for spike again\u202c</strong>\".",
		"body": "Even more replies",
		"icon": "edit-user-talk",
		"links": {
			"primary": {
				"url": "https://en.wikipedia.org/wiki/User_talk:TSevener_(WMF)?markasread=223017027&markasreadwiki=enwiki#Testing_new_section_notification_for_spike_again",
				"label": "View message"
			},
			"secondary": [{
					"url": "https://en.wikipedia.org/wiki/User:Tsevener",
					"label": "\u202aTsevener\u202c",
					"tooltip": "",
					"description": "",
					"icon": "userAvatar",
					"prioritized": ""
				},
				{
					"url": "https://en.wikipedia.org/w/index.php?title=User_talk:TSevener_(WMF)&oldid=prev&diff=1033965765",
					"label": "View changes",
					"description": "",
					"icon": "changes",
					"prioritized": ""
				}
			]
		},
		"iconUrl": "/w/extensions/Echo/modules/icons/edit-user-talk-progressive.svg"
	}
}

I haven't yet found direct documentation on this payload, but after triggering and examining many of them, and looking at documentation here and here, I feel pretty certain that wiki, id, type, category, section, timestamp, and header will always be available. Every notification I tried also had primary > url & label options returned, but primary link is not required in the documentation so we may get notifications without any actionable link. We can still try to use any of this other data if it exists, we just need to be able to handle the absence of it too. Hope this helps! Happy to answer any further questions on this.

cmadeo updated the task description. (Show Details)

Thanks @Tsevener, this is super helpful! I also found some definitions related to these fields on related mediaWikipages which I hope will help with clarifying in designs!

A few questions and thoughts:

  • Do you happen to know what the ID is and what information we can extract from it?
  • Do you know if we can assume an associated icon from any of the fields above?
  • Unfortunately it looks like 'Header' (which is the main content of the notification) is just a text blob, do you think that it means that it might be hard to pull out relevant user IDs from notifications? In your example you shared above it looks like your username is wrapped in some way, can we use that?

@cmadeo

I also found some definitions related to these fields on related mediaWikipages which I hope will help with clarifying in designs!

Thank you!

Do you happen to know what the ID is and what information we can extract from it?

I assume it uniquely identifies the notification, but whether it is unique globally or just for that wiki I'm not sure. I don't think it's meant to map to anything else. The API documentation is here but there isn't much documentation on the response fields, just what to request.

Unfortunately it looks like 'Header' (which is the main content of the notification) is just a text blob, do you think that it means that it might be hard to pull out relevant user IDs from notifications? In your example you shared above it looks like your username is wrapped in some way, can we use that?

Correct, I think the only thing we could really do for this ticket is strip the html from the header field and display that. agent does represent the user that triggered the notification in this particular example, but we shouldn't depend on it being there for whatever future notification types come through Echo.

Just to be clear, my hope is we won't need this super generic handling for all notifications, just the ones the app doesn't recognize. If the app detects an "edit-user-talk" type, we could use the name from the agent field and page title from the title field and construct "[username] left a message on [title]". And add links around each accordingly, and whatever custom UI that indicates a talk page edit. And so on for all the other recognized types. (One caveat that could mess up these plans is mentioned in question 4 here, we should discuss this in sync).

Do you know if we can assume an associated icon from any of the fields above?

You could design a generic "alert" and "notice" icon (and maybe a fallback even more generic icon or empty space) based on their "section" value, it seems like that's likely to always be there. A 3rd type could come in the future, hence the need for a fallback empty space or even more generic icon for these.

Thanks for all of these clarifications @Tsevener and all of the discovery work you've been doing!!!

LGoto triaged this task as Medium priority.Jul 22 2021, 7:03 PM
cmadeo updated the task description. (Show Details)

@cmadeo can you elaborate on what [Type-ID] and [Dynamic-Action] are? The "type" value will be probably be some form like "edit-user-talk" (but we won't know exactly what it is), the best we could do is display that in the UI in all it's hyphenated glory, which I don't think is what you want.

@Tsevener I thought that maybe [Type ID] could be used to identify what type of notice/alert it is (eg like a talk page message). I think it's important that we let people know what the general category of notification this is, but happy to use whatever field will get us the clearest/most understandable results. This was just my guess from looking at the JSON :(

Dynamic Action are secondary links that "allow API-directed actions ('dynamic' actions) for actions like 'stop watching a page' or others that require the front-end to request an AJAX request to the API directly from the notification." If we can't support this it's okay.

@cmadeo oh I see, I think we could maybe then lean on the "section" value from the JSON response. If it's "alert" say Alert, if it's "message" say Message, is that closer to what you were thinking?

Re: dynamic action, thanks for explaining! I found an example object with one. It shouldn't be any harder than the primary and secondary links, so I don't see a problem with it.

@Tsevener ah! I was kind of hoping for more granular (like the 'type' column on this spreadsheet: https://docs.google.com/spreadsheets/d/1RSDY7ZZ4nOzUUOnZtJvLBJ1bDjrxP5gL_22dit38LDM/edit?usp=sharing) but the less granular seems like an okay fall back if we need to.