diff --git a/browser/components/newtab/content-src/asrouter/docs/index.rst b/browser/components/newtab/content-src/asrouter/docs/index.rst index c28ccd206440..0d224ac1f685 100644 --- a/browser/components/newtab/content-src/asrouter/docs/index.rst +++ b/browser/components/newtab/content-src/asrouter/docs/index.rst @@ -2,14 +2,94 @@ Messaging System ================ -Someday, this document will contain a high-level description of ASRouter. -In the meantime, here are some documents about specific features: +Vision +------ +Firefox must be an opinionated user agent that keeps folks safe, informed and +effective while browsing the Web. In order to have an opinion, Firefox must +have a voice. +That voice will **respect the user’s attention** while surfacing contextually +relevant and timely information tailored to their individual needs and choices. + +What does Messaging System support? +----------------------------------- +There are several key windows of opportunity, such as the first-run activation +phase or coordinated feature releases, where Firefox engages with users. + +The Firefox Messaging System supports this engagement by targeting messages +exactly to the users who need to see them and enables the development of new +user messages that can be easily tested and deployed. It offers standard +mechanisms to measure user engagement and to perform user messaging experiments +with reduced effort across engineering teams and a faster delivery cycle from +ideation to analysis of results. + +This translates to **users seeing fewer and more relevant in-product +messages**, while supporting fast delivery, experimentation, and protection of +our users time and attention. + +Messaging System Overview +------------------------- +At the core of the Firefox Messaging System is the Messaging System Router +(called ASRouter for historical reasons). The router is a generalized Firefox +component and set of conventions that provides: + +* Flexible and configurable routing of local or remote Messages to UI + Templates. This allows new message campaigns to be started and controlled + on or off-trains +* Traffic Cop message sequencing and intermediation to prevent multiple + messages being concurrently shown +* Programmable message targeting language to show the right message to the + right user at the right time +* A template library of reusable Message and Notification UIs +* Full compatibility with Normandy pref-flip experiments +* Generalized and privacy conscious event telemetry +* Flexible Frequency Capping to mitigate user message fatigue +* Localized off train Messages +* Powerful development/debugging/QA tools on about:newtab#devtools + +Message Routing +--------------- +.. image:: ./message-routing-overview.png + :align: center + :alt: Message Routing Overview + +The Firefox Messaging System implements a separation-of-concerns pattern for +Messages, UI Templates, and Timing/Targeting mechanisms. This allows us to +maintain a high standard of security and quality while still allowing for +maximum flexibility around content creation. + +UI Templates +------------ +We have built a library of reusable Notification and Message interfaces which +land in the Firefox codebase and ride the trains. These templates have a +defined schema according to the available design components (e.g. titles, text, +icons) and access to a set of enhanced user actions such as triggering URLs, +launching menus, or installing addons, which can be attached to interactive +elements (such as buttons). + +Current templates include\: + +* What's New Panel - an icon in the toolbar and menu item that appears if a + message is available in the panel, usually after major Firefox releases +* Moments Page - appears on start-up as a full content page +* Contextual Feature Recommendation - highlighted word in the Location Bar + that, if clicked, drops down a panel with information about a feature + relevant to that user at that time +* First Run - shown on startup in a content page as a set of onboarding cards + with calls to action that persist for several days +* Snippets - short messages that appear on New Tab Page to highlight products, + features and initiatives +* Badging - A colorful dot to highlight icons in the toolbar or menu items in + order to draw attention with minimal interruption + +Detailed Docs +------------- .. In theory, we ought to be able to use the :glob: directive here to .. automatically generate the list below. For unknown reasons, however, .. `mach doc` _sometimes_ gets confused and refuses to find patterns like .. `*.md`. .. toctree:: + :maxdepth: 2 debugging-docs experiment-guide diff --git a/browser/components/newtab/content-src/asrouter/docs/message-routing-overview.png b/browser/components/newtab/content-src/asrouter/docs/message-routing-overview.png new file mode 100644 index 000000000000..0ec2ec3c14a6 Binary files /dev/null and b/browser/components/newtab/content-src/asrouter/docs/message-routing-overview.png differ