Bug 1634054 - Document trigger and button actions for CFRs r=k88hudson

Differential Revision: https://phabricator.services.mozilla.com/D73269

browser/components/newtab/content-src/asrouter/docs/index.rst

@@ -96,4 +96,3 @@ Detailed Docs
   first-run
   targeting-attributes
   targeting-guide
-  user-actions

browser/components/newtab/content-src/asrouter/docs/trigger-listeners.md

@@ -0,0 +1,94 @@
+# Trigger Listeners
+
+A set of action listeners that can be used to trigger CFR messages.
+
+## Usage
+
+[As part of the CFR definition](https://searchfox.org/mozilla-central/rev/2bfe3415fb3a2fba9b1c694bc0b376365e086927/browser/components/newtab/lib/CFRMessageProvider.jsm#194) the message can register at most one trigger used to decide when the message is shown.
+
+Most triggers (unless otherwise specified) take the same arguments of `hosts` and/or `patterns`
+used to target the message to specific websites.
+
+```javascript
+// Optional set of hosts to filter out triggers only to certain websites
+let params: string[];
+// Optional set of [match patterns](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Match_patterns) to filter out triggers only to certain websites
+let patterns: string[];
+```
+
+```javascript
+{
+  ...
+  // Show the message when opening mozilla.org
+  "trigger": { "id": "openURL", "params": ["mozilla.org", "www.mozilla.org"] }
+  ...
+}
+```
+
+```javascript
+{
+  ...
+  // Show the message when opening any HTTP, HTTPS URL.
+  trigger: { id: "openURL", patterns: ["*://*/*"] }
+  ...
+}
+```
+
+## Available trigger actions
+
+### `openArticleURL`
+
+Happens when the user loads a Reader Mode compatible webpage.
+
+### `openBookmarkedURL`
+
+Happens when the user bookmarks or navigates to a bookmarked URL.
+
+Does not filter by host or patterns.
+
+### `frequentVisits`
+
+Happens every time a user navigates (or switches tab to) to any of the `hosts` or `patterns` arguments
+provided. Additionally it stores timestamps of these visits that are provided back to the targeting context.
+They can be used inside of the targeting expression:
+
+```javascript
+// Has at least 3 visits in the past hour
+recentVisits[.timestamp > (currentDate|date - 3600 * 1000 * 1)]|length >= 3
+
+```
+
+```typescript
+interface visit {
+  host: string,
+  timestamp: UnixTimestamp
+};
+// Host and timestamp for every visit to "Host"
+let recentVisits: visit[];
+```
+
+### `openURL`
+
+Happens every time the user loads a new URL that matches the provided `hosts` or `patterns`.
+
+### `newSavedLogin`
+
+Happens every time the user saves or updates a login via the login capture doorhanger.
+Provides a `type` to diferentiate between the two events that can be used in targeting.
+
+Does not filter by host or patterns.
+
+```typescript
+let type = "update" | "save";
+```
+
+### `contentBlocking`
+
+Happens every time there is a content blocked event. Provides a context of the
+number of pages loaded in the current browsing session that can be used in targeting.
+
+Does not filter by host or patterns.
+
+```typescript
+let pageLoad = number;
+```

toolkit/components/messaging-system/schemas/SpecialMessageActionSchemas.md

@@ -45,7 +45,13 @@ Example:
 
 ### `OPEN_ABOUT_PAGE`
 
-* args: `string` (a valid about page without the `about:` prefix)
+* args:
+```ts
+{
+  args: string, // (a valid about page without the `about:` prefix)
+  entrypoint?: string, // URL search param used for referrals
+}
+```
 
 Opens a given about page
 
@@ -60,7 +66,11 @@ Example:
 
 ### `OPEN_PREFERENCES_PAGE`
 
-* args: `string` (a category accessible via a `#`)
+* args:
+```
+{
+  args?: string, // (a category accessible via a `#`)
+  entrypoint?: string // URL search param used to referrals
 
 Opens `about:preferences` with an optional category accessible via a `#` in the URL (e.g. `about:preferences#home`).
 
@@ -107,7 +117,7 @@ Pins the currently focused tab.
 
 Opens an oauth flow to enable Firefox Monitor at a given `url` and adds Firefox metrics that user given a set of `flowRequestParams`.
 
-### `url`
+#### `url`
 
 The URL should start with `https://monitor.firefox.com/oauth/init` and add various metrics tags as search params, including:
 
@@ -118,7 +128,7 @@ The URL should start with `https://monitor.firefox.com/oauth/init` and add vario
 
 You should verify the values of these search params with whoever is doing the data analysis (e.g. Leif Oines).
 
-### `flowRequestParams`
+#### `flowRequestParams`
 
 These params are used by Firefox to add information specific to that individual user to the final oauth URL. You should include:
 
@@ -130,7 +140,7 @@ The `entrypoint` and `form_type` values should match the encoded values in your
 
 You should verify the values with whoever is doing the data analysis (e.g. Leif Oines).
 
-### Example
+#### Example
 
 ```json
 {
@@ -145,3 +155,48 @@ You should verify the values with whoever is doing the data analysis (e.g. Leif
   }
 }
 ```
+
+### `HIGHLIGHT_FEATURE`
+
+Can be used to highlight (show a light blue overlay) a certain button or part of the browser UI.
+
+* args: `string` a [valid targeting defined in the UITour](https://searchfox.org/mozilla-central/rev/7fd1c1c34923ece7ad8c822bee062dd0491d64dc/browser/components/uitour/UITour.jsm#108)
+
+### `INSTALL_ADDON_FROM_URL`
+
+Can be used to install an addon from addons.mozilla.org.
+
+* args:
+```ts
+{
+  url: string,
+  telemetrySource?: string
+};
+```
+
+### `OPEN_PROTECTION_REPORT`
+
+Opens `about:protections`
+
+### `OPEN_PROTECTION_PANEL`
+
+Opens the protection panel behind on the lock icon of the awesomebar
+
+### `DISABLE_STP_DOORHANGERS`
+
+Disables all Social Tracking Protection messages
+
+* args: (none)
+
+### `OPEN_AWESOME_BAR`
+
+Focuses and expands the awesome bar.
+
+* args: (none)
+
+### `CANCEL`
+
+No-op action used to dismiss CFR notifications (but not remove or block them)
+
+* args: (none)
+

toolkit/components/messaging-system/test/browser/specialMessageActions/browser.ini

@@ -3,6 +3,7 @@ prefs =
   identity.fxaccounts.remote.root=https://example.com/
 support-files =
   head.js
+  ../../../schemas/SpecialMessageActionSchemas.md
 
 [browser_sma_open_about_page.js]
 [browser_sma_open_awesome_bar.js]
@@ -14,4 +15,4 @@ support-files =
 [browser_sma_show_firefox_accounts.js]
 [browser_sma_show_migration_wizard.js]
 [browser_sma.js]
-
+[browser_sma_docs.js]

toolkit/components/messaging-system/test/browser/specialMessageActions/browser_sma_docs.js

@@ -0,0 +1,31 @@
+const TEST_URL =
+  "https://example.com/browser/toolkit/components/messaging-system/test/browser/specialMessageActions/SpecialMessageActionSchemas.md";
+
+const { SpecialMessageActionSchemas } = ChromeUtils.import(
+  "resource://testing-common/SpecialMessageActionSchemas.js"
+);
+
+function getHeadingsFromDocs(docs) {
+  const re = /### `(\w+)`/g;
+  const found = [];
+  let match = 1;
+  while (match) {
+    match = re.exec(docs);
+    if (match) {
+      found.push(match[1]);
+    }
+  }
+  return found;
+}
+
+add_task(async function test_sma_docs() {
+  let request = await fetch(TEST_URL);
+  let docs = await request.text();
+  let headings = getHeadingsFromDocs(docs);
+  for (let action_name of Object.keys(SpecialMessageActionSchemas)) {
+    Assert.ok(
+      headings.includes(action_name),
+      `${action_name} not found in SpecialMessageActionSchemas.md`
+    );
+  }
+});