Bug 1502384 - Link to debugging guide for ASR Devtools

content-src/asrouter/README.md

@@ -30,23 +30,4 @@ Name | Used for | Type | Example value
 }
 ```
 
-## Admin Interface
-
-* Navigate to `about:newtab#asrouter`
-  * See all available messages and message providers
-  * Block, unblock or force show a specific message
-
-## Snippet Preview
-
-* Whitelist the provider host that will serve the messages
-  * In `about:config`, `browser.newtab.activity-stream.asrouter.whitelistHosts` can contain a array of hosts
-  * Example value `["gist.github.com", "gist.githubusercontent.com", "localhost:8000"]`
-  * Errors are surfaced in the `Console` tab of the `Browser Toolbox` ([read how to enable](https://developer.mozilla.org/en-US/docs/Tools/Browser_Toolbox))
-* Navigate to `about:newtab?endpoint=<URL>`
-  * Example `https://gist.githubusercontent.com/piatra/70234f08696c0a0509d7ba5568cd830f/raw/68370f34abc134142c64b6f0a9b9258a06de7aa3/messages.json`
-  * URL should be from an endpoint that was just whitelisted
-  * The snippet preview should imediately load
-  * The endpoint must be HTTPS, the host must be whitelisted
-  * Errors are surfaced in the `Console` tab of the `Browser Toolbox`
-
 ### [Snippet message format documentation](https://github.com/mozilla/activity-stream/blob/master/content-src/asrouter/schemas/message-format.md)

content-src/asrouter/docs/debugging-docs.md

@@ -0,0 +1,76 @@
+# Using ASRouter Devtools
+
+## How to enable ASRouter devtools
+- In `about:config`, set `browser.newtabpage.activity-stream.asrouter.devtoolsEnabled` to `true`
+- Visit `about:newtab#asrouter` to see the devtools.
+
+## Overview of ASRouter devtools
+
+![Devtools image](./debugging-guide.png)
+
+## How to enable/disable a provider
+
+To enable a provider such as `snippets`, Look at the list of "Message Providers" at the top of the page. Make sure the checkbox is checked next to the provider you want to enable.
+
+To disable it, uncheck the checkbox. You should see a red label indicating the provider is now disabled.
+
+## How to see all messages from a provider
+
+(Only available in Firefox 65+)
+
+In order to see all active messages for a current provider such as `snippets`, use the drop down selector under the "Messages" section. Select the name of the provider you are interested in.
+
+The messages on the page should now be filtered to include only the provider you selected.
+
+## How to test telemetry pings
+
+To test telemetry pings, complete the the following steps:
+
+- In about:config, set:
+  - `browser.newtabpage.activity-stream.telemetry` to `true`
+  - `browser.ping-centre.log` to `true`
+- Open the Browser Toolbox devtools (Tools > Developer > Browser Toolbox) and switch to the console tab. Add a filter for for `activity-stream-router` to only display relevant pings:
+
+![Devtools telemetry pong](./telemetry-screenshot.png)
+
+You should now see pings show up as you view/interact with ASR messages/templates.
+
+## Snippets debugging
+
+### How to test legacy snippets
+
+To make sure the legacy snippets system is still running properly, do the following:
+
+- Load test data for legacy snippets. In about:config, set `browser.aboutHomeSnippets.updateUrl` to `https://snippets.allizom.org/%STARTPAGE_VERSION%/%NAME%/%VERSION%/%APPBUILDID%/%BUILD_TARGET%/%LOCALE%/%CHANNEL%/%OS_VERSION%/%DISTRIBUTION%/%DISTRIBUTION_VERSION%/`
+- Disable ASR snippets
+  - set up your ASR devtools (see steps above)
+  - visit `about:newtab#asrouter`
+  - Uncheck the checkbox next to snippets
+- Check `about:newtab` to make sure legacy snippets are loading
+  - visit `about:newtab`
+  - Type gSnippetsMap.clear() into the devtools console and refresh the page
+  - Open the devtools again
+  - Ensure you see the message “Legacy snippets: Successfully added snippets.”
+  - Ensure you visually see snippets on the page
+
+### How to view preview URLs
+
+Follow these steps to view preview URLs (e.g. `about:newtab?endpoint=https://gist.githubusercontent.com/piatra/d193ca7e0f513cc19fc6a1d396c214f7/raw/8bcaf9548212e4c613577e839198cc14e7317630/newsletter_snippet.json`)
+
+#### IMPORTANT NOTES
+- Links to URLs starting with `about:newtab` cannot be clicked on directly. They must be copy and pasted into the address bar.
+- Previews should only be tested in `Firefox 64` and later.
+- The endpoint must be HTTPS, the host must be whitelisted (see testing instructions below)
+- Errors are surfaced in the `Console` tab of the `Browser Toolbox`
+
+#### Testing instructions
+- If your endpoint URL has a host name of `snippets-admin.mozilla.org`, you can paste the URL into the address bar view it without any further steps.
+- If your endpoint URL  starts with some other host name, it must be **whitelisted**. Open the Browser Toolbox devtools (Tools > Developer > Browser Toolbox) and paste the following code (where `gist.githubusercontent.com` is the hostname of your endpoint URL):
+```js
+Services.prefs.setStringPref(
+  "browser.newtab.activity-stream.asrouter.whitelistHosts",
+  "[\"gist.githubusercontent.com\"]"
+);
+```
+- Restart the browser
+- You should now be able to paste the URL into the address bar and view it.

content-src/components/ASRouterAdmin/ASRouterAdmin.jsx

@@ -355,6 +355,13 @@ export class ASRouterAdmin extends React.PureComponent {
   render() {
     return (<div className="asrouter-admin outer-wrapper">
       <h1>AS Router Admin</h1>
+      <p className="helpLink">
+        <span className="icon icon-small-spacer icon-info" />
+        {" "}
+        <span>
+          Need help using these tools? Check out our <a target="blank" href="https://github.com/mozilla/activity-stream/blob/master/content-src/asrouter/docs/debugging-docs.md">documentation</a>
+        </span>
+      </p>
       <h2>Targeting Utilities</h2>
       <button className="button" onClick={this.expireCache}>Expire Cache</button> (This expires the cache in ASR Targeting for bookmarks and top sites)
       <h2>Message Providers <button title="Restore all provider settings that ship with Firefox" className="button" onClick={this.resetPref}>Restore default prefs</button></h2>

content-src/components/ASRouterAdmin/ASRouterAdmin.scss

@@ -108,4 +108,15 @@
   .errorState {
     border: 1px solid $red-60;
   }
+
+  .helpLink {
+    padding: 10px;
+    display: flex;
+    background: $yellow-50;
+    border-radius: 3px;
+
+    a {
+      text-decoration: underline;
+    }
+  }
 }