Incorporate feedback from Osmose and pdehaan

2018-11-12 15:48:19 -08:00 · 2018-11-12 15:48:19 -08:00 · 54ed54d147
--- a/README.md
+++ b/README.md
@ -3,12 +3,7 @@
 Price Wise is a Firefox extension that tracks price changes to help you find the best time to buy.


-## User Experience
-
-See [UX specifications](https://mozilla.invisionapp.com/share/UFNSHAIMT4V#/screens/317130676_Artboard_1).
-
-
-## Telemetry
+## Data Collection

 See [METRICS.md](./docs/METRICS.md).

@ -60,24 +55,6 @@ Note: This will install the extension as an [unsigned](https://wiki.mozilla.org/
 | `pipenv run test` | Run test suite (See "Running Tests" for setup) |


-## Code Organization
-
- `src/background` contains the background scripts that trigger UI elements (such as the browserAction toolbar button) and periodically check for price updates.
- `src/browser_action` contains the toolbar popup for managing the list of currently-tracked products and tracking new products.
- `src/config` contains the scripts used to fetch config values specified in [config.js](src/config.js).
- `src/experiment_apis` contains the [experimental APIs](https://firefox-source-docs.mozilla.org/toolkit/components/extensions/webextensions/basics.html#webextensions-experiments) used to read [preference values](#preferences) and listen for chrome-privileged Firefox events. 
- `src/extraction` contains the content scripts that extract product information from product web pages.
- `src/img` contains all the non-favicon images used by the extension.
- `src/state` contains the Redux-based code for managing global extension state.
- `src/styles` contains Firefox-specific CSS property values stored as variables.
- `src/telemetry` contains the scripts used to register and record extension [telemetry events](https://firefox-source-docs.mozilla.org/toolkit/components/telemetry/telemetry/collection/events.html) in different contexts.
- `src/tests` contains the automated test suite.
- `config.js` contains the static configuration settings for the extension, including default values if [override preferences](#preferences) are not set.
- `manifest.json` contains basic metadata about the extension.
- `privacy.js` handles checking privacy settings to gate functionality across the extension.
- `utils.js` contains general utility functions that can be used across the extension.
-
-
 ## Data Storage

 Global state for the add-on is managed via [Redux][]. Any time the data is changed, it is persisted to the [add-on local storage][localstorage].
@ -125,32 +102,24 @@ The following preferences can be set to customize the extension's behavior for t

 <dl>
  <dt><code>extensions.shopping-testpilot@mozilla.org.extractionAllowlist</code></dt>
-  <dd>Preference type: string. List of domains (<code>{Array.string}</code> or <code>*</code>) that extraction is performed on. Can be set to <code>*</code> to enable extraction on all sites (default: <code>extractionAllowlist</code> value specified in [config.js](src/config.js).</dd>
+  <dd>(<code>string</code>) List of domains (<code>{Array.string}</code> or <code>*</code>) that extraction is performed on. Can be set to <code>*</code> to enable extraction on all sites.</dd>

  <dt><code>extensions.shopping-testpilot@mozilla.org.priceCheckInterval</code></dt>
-  <dd>Preference type: integer. Time to wait between price checks for a product in milliseconds (default: <code>21600000</code> or 6 hours).</dd>
+  <dd>(<code>integer</code>) Time to wait between price checks for a product in milliseconds.</dd>

  <dt><code>extensions.shopping-testpilot@mozilla.org.priceCheckTimeoutInterval</code></dt>
-  <dd>Preference type: integer. Time to wait between checking if we should fetch new prices in milliseconds (default: <code>900000</code> or 15 minutes).</dd>
+  <dd>(<code>integer</code>) Time to wait between checking if we should fetch new prices in milliseconds.</dd>

  <dt><code>extensions.shopping-testpilot@mozilla.org.iframeTimeout</code></dt>
-  <dd>Preference type: integer. Delay before removing iframes created during price checks in milliseconds (default: <code>60000</code>or 1 minute).</dd>
+  <dd>(<code>integer</code>) Delay before removing iframes created during price checks in milliseconds.</dd>

  <dt><code>extensions.shopping-testpilot@mozilla.org.alertPercentThreshold</code></dt>
-  <dd>Preference type: integer. The percentage drop in price on which to trigger a price alert compared to the last high price (See `price_last_high` in [METRICS.md](./docs/METRICS.md)) default: <code>5</code> or 5%).</dd>
+  <dd>(<code>integer</code>) The percentage drop in price on which to trigger a price alert compared to the last high price (See <code>price_last_high</code> in [METRICS.md](./docs/METRICS.md)).</dd>

  <dt><code>extensions.shopping-testpilot@mozilla.org.alertAbsoluteThreshold</code></dt>
-  <dd>Preference type: integer. The absolute drop in price on which to trigger a price alert compared to the last high price (see `price_last_high` in [METRICS.md](./docs/METRICS.md)) in cents (default: <code>1000</code> or $10).</dd>
+  <dd>(<code>integer</code>) The absolute drop in price on which to trigger a price alert compared to the last high price (see `price_last_high` in [METRICS.md](./docs/METRICS.md)) in currency subunits (e.g. cents for USD).</dd>
 </dl>

-### Test Page
-
-The extension can be tested with this [Fake Product Page](http://www.mkelly.me/fake-product-page/), which randomly generates a price each time it loads.
-
-Query strings may be used to:
-* Set the max price: e.g.  http://www.mkelly.me/fake-product-page/?max=10000
-* Fix the price to a particular value: e.g. http://www.mkelly.me/fake-product-page/?dollars=10000
-

 ## Releasing a New Version

--- a/docs/METRICS.md
+++ b/docs/METRICS.md
@ -13,8 +13,8 @@ A summary of the metrics the Price Wise extension will record.
 * **Fathom**: A [JavaScript framework](https://github.com/erikrose/fathom) used to extract product information from a Product Page.
 * **Price Alert**: An alert that occurs when a tracked product's price _decreases_ below a certain absolute or percentage threshold. For the MVP, the default thresholds are specified in `./src/config.js`.
 * **Product Card**: A product list item in the list of tracked products for which the user has opted to receive Price Alerts displayed on the browserAction popup. Each Product Card displays the product title, image and price among other information.
-* **Product Page**: A webpage ([example](https://www.amazon.com/LEGO-Fantastic-Beasts-Grindelwald-Grindelwalds/dp/B07BKQXCZR/ref=sr_1_3_sspa?s=toys-and-games&ie=UTF8&qid=1538418041&sr=1-3-spons&keywords=legos&psc=1)) displaying a single product that the user could purchase online.
-* **Supported Sites**: For the initial launch (a.k.a. MVP, Minimum Viable Product) of this extension, we are limiting the sites supported by this feature to [five websites](https://github.com/mozilla/price-wise/issues/36#issuecomment-409641491): Amazon, Ebay, Walmart, Home Depot and Best Buy.
+* **Product Page**: A webpage displaying a single product that the user could purchase online.
+* **Supported Sites**: For the initial launch (a.k.a. MVP, Minimum Viable Product) of this extension, we are limiting the sites supported by this feature to [five websites](https://github.com/mozilla/price-wise/issues/36#issuecomment-409641491): Amazon, eBay, Walmart, Home Depot and Best Buy.
 * **Survey**: a short survey collecting user feedback.
 * **Onboarding Popup**: The popup displayed when the user has zero products tracked, including the first time the popup is opened.

@ -63,7 +63,7 @@ Note: For any questions related to general user shopping behavior, the data abou

 ### Questions to answer in future experiments

-While some of these questions may be partially answerable by this extension, answering them thorougly requires controlled A/B testing and/or more extensive data collection on more sites.
+While some of these questions may be partially answerable by this extension, answering them thoroughly requires controlled A/B testing and/or more extensive data collection on more sites.

 #### Does it affect user behavior in Firefox?
 - Does it increase shopping browsing?
@ -80,116 +80,104 @@ While some of these questions may be partially answerable by this extension, ans
 - On what sites do users shop?


-## Sample Pings
+## Sample Events

 We will be sending pings using [Event Telemetry](https://firefox-source-docs.mozilla.org/toolkit/components/telemetry/telemetry/collection/events.html) via the [WebExtensions Telemetry API](https://bugzilla.mozilla.org/show_bug.cgi?id=1280234).

-Each event will exist as part of the [`event` ping](https://firefox-source-docs.mozilla.org/toolkit/components/telemetry/telemetry/data/event-ping.html) under `payload.events.dynamic` as an array (see Appendix B for how to view extension events in `about:telemetry`). The data types of individual fields for each event follow the Event Telemetry [serialization format](https://firefox-source-docs.mozilla.org/toolkit/components/telemetry/telemetry/collection/events.html#serialization-format).
+The data types of individual fields for each event follow the Event Telemetry [serialization format](https://firefox-source-docs.mozilla.org/toolkit/components/telemetry/telemetry/collection/events.html#serialization-format).

 The telemetry category for events is `'extension.price_wise'`.

-Below is a sample `event` ping for when the user visits a supported page and adds the product on that page.
+Below is a sample list of events recorded when the user visits a supported page and adds the product on that page.

 ```javascript
-{
-  "type": "event",
-  //...
-  "payload": {
-    //...
-    "events": {
-      "dynamic": [
-        [
-          154572,
-          "extension.price_wise",
-          "visit_supported_site",
-          "supported_site",
-          null,
-          {
-            "tracked_prods": "0",
-            "privacy_dnt": "false",
-            "privacy_tp": "private_browsing",
-            "privacy_cookie": "allow_all"
-          }
-        ],
-        [
-          154592,
-          "extension.price_wise",
-          "attempt_extraction",
-          "product_page",
-          null,
-          {
-            "extraction_id": "d7031676-74aa-41b7-a730-c26fc9617dd5",
-            "is_bg_update": "false",
-            "tracked_prods": "0",
-            "privacy_dnt": "false",
-            "privacy_tp": "private_browsing",
-            "privacy_cookie": "allow_all"
-          }
-        ],
-        [
-          154597,
-          "extension.price_wise",
-          "complete_extraction",
-          "product_page",
-          null,
-          {
-            "extraction_id": "d7031676-74aa-41b7-a730-c26fc9617dd5",
-            "is_bg_update": "false",
-            "method": "css_selectors",
-            "tracked_prods": "0",
-            "privacy_dnt": "false",
-            "privacy_tp": "private_browsing",
-            "privacy_cookie": "allow_all"
-          }
-        ],
-        [
-          154601,
-          "extension.price_wise",
-          "badge_toolbar_button",
-          "toolbar_button",
-          null,
-          {
-            "badge_type": "add",
-            "tracked_prods": "0",
-            "privacy_dnt": "false",
-            "privacy_tp": "private_browsing",
-            "privacy_cookie": "allow_all"
-          }
-        ],
-        [
-          156806,
-          "extension.price_wise",
-          "open_popup",
-          "toolbar_button",
-          null,
-          {
-            "badge_type": "add",
-            "tracked_prods": "0",
-            "privacy_dnt": "false",
-            "privacy_tp": "private_browsing",
-            "privacy_cookie": "allow_all"
-          }
-        ],
-        [
-          158056,
-          "extension.price_wise",
-          "add_product",
-          "add_button",
-          null,
-          {
-            "price": "1100",
-            "product_key": "791893d7-1303-4e11-9913-c2ce762aa691",
-            "tracked_prods": "1",
-            "privacy_dnt": "false",
-            "privacy_tp": "private_browsing",
-            "privacy_cookie": "allow_all"
-          }
-        ]
-      ]
-    }
-  },
-  //...
-}
+[
+  154572,
+  "extension.price_wise",
+  "visit_supported_site",
+  "supported_site",
+  null,
+  {
+    "tracked_prods": "0",
+    "privacy_dnt": "false",
+    "privacy_tp": "private_browsing",
+    "privacy_cookie": "allow_all"
+  }
+],
+[
+  154592,
+  "extension.price_wise",
+  "attempt_extraction",
+  "product_page",
+  null,
+  {
+    "extraction_id": "d7031676-74aa-41b7-a730-c26fc9617dd5",
+    "is_bg_update": "false",
+    "tracked_prods": "0",
+    "privacy_dnt": "false",
+    "privacy_tp": "private_browsing",
+    "privacy_cookie": "allow_all"
+  }
+],
+[
+  154597,
+  "extension.price_wise",
+  "complete_extraction",
+  "product_page",
+  null,
+  {
+    "extraction_id": "d7031676-74aa-41b7-a730-c26fc9617dd5",
+    "is_bg_update": "false",
+    "method": "css_selectors",
+    "tracked_prods": "0",
+    "privacy_dnt": "false",
+    "privacy_tp": "private_browsing",
+    "privacy_cookie": "allow_all"
+  }
+],
+[
+  154601,
+  "extension.price_wise",
+  "badge_toolbar_button",
+  "toolbar_button",
+  null,
+  {
+    "badge_type": "add",
+    "tracked_prods": "0",
+    "privacy_dnt": "false",
+    "privacy_tp": "private_browsing",
+    "privacy_cookie": "allow_all"
+  }
+],
+[
+  156806,
+  "extension.price_wise",
+  "open_popup",
+  "toolbar_button",
+  null,
+  {
+    "badge_type": "add",
+    "tracked_prods": "0",
+    "privacy_dnt": "false",
+    "privacy_tp": "private_browsing",
+    "privacy_cookie": "allow_all"
+  }
+],
+[
+  158056,
+  "extension.price_wise",
+  "add_product",
+  "add_button",
+  null,
+  {
+    "price": "1100",
+    "product_key": "791893d7-1303-4e11-9913-c2ce762aa691",
+    "tracked_prods": "1",
+    "privacy_dnt": "false",
+    "privacy_tp": "private_browsing",
+    "privacy_cookie": "allow_all"
+  }
+]
 ```


@ -218,7 +206,7 @@ Some `extra_keys` are sent with every telemetry event recorded by the extension:
 - `'element'`: The extension UI element that the user clicked to open a page in a new tab. Note: All `*_link` elements exist in the Onboarding Popup only. One of...
  - `'amazon_link'`: Sends the user to Amazon.
  - `'best_buy_link'`: Sends the user to Best Buy.
-  - `'ebay_link'`: Sends the user to Ebay.
+  - `'ebay_link'`: Sends the user to eBay.
  - `'feedback_button'`: Sends the user to a feedback Survey.
  - `'help_button'`: Sends the user to a Price Wise support.mozilla.org page.
  - `'home_depot_link'`: Sends the user to Home Depot.
@ -472,7 +460,7 @@ No telemetry will be sent from the extension in the following additional cases:

 Fired when the user uninstalls the extension.

-This event, along with all other add-on lifecycle events, is recorded by the Addons Manager's event telemetry in Firefox. It will exist as part of the `event` ping under `payload.events.parent` as an array.
+This event, along with all other add-on lifecycle events, is recorded by the Addons Manager's event telemetry in Firefox.

 This event will be fired under the `addonsManager` telemetry category.

@ -480,56 +468,18 @@ Notes:
 - Other lifecycle events such as `install` may have a different event structure than `uninstall`. Since `addonsManager` events are registered statically, you can view how each event is structured in [Events.yaml](https://searchfox.org/mozilla-central/source/toolkit/components/telemetry/Events.yaml) in the Firefox source code.
 - The `addonsManager` events are only available in Firefox version 64 and later versions.

-#### Sample Ping
+#### Sample Event

 ```javascript
-{
-  "type": "event",
-  //...
-  "payload": {
-    //...
-    "events": {
-      "parent": [
-        [
-          9792,
-          "addonsManager",
-          "uninstall",
-          "extension",
-          "shopping-testpilot@mozilla.org",
-          {
-            "source": "testpilot"
-            // ...
-          }
-        ]
-      ]
-    }
-  },
-  //...
-}
+[
+  9792,
+  "addonsManager",
+  "uninstall",
+  "extension",
+  "shopping-testpilot@mozilla.org",
+  {
+    "source": "testpilot"
+    // ...
+  }
+]
 ```
-
-
-### Appendix B: How to view Price Wise events in `about:telemetry`
-
-Note: Event Telemetry for this extension may be disabled for certain situations, see [Opt Out](#opt-out).
-
-#### Current Session
-
-To view event telemetry for the current session:
-
-1. Navigate to `about:telemetry`.
-2. Click 'Events' in the sidebar menu.
-  - Note: This menu item is not present until an event has been recorded for the current session. If you don't see it, trigger one of the events as described in this document (e.g. `open_popup`) and refresh the page.
-3. On the top right corner of the next page, click 'dynamic' in the dropdown menu.
-4. You should see a table displayed with all the recorded dynamic events for the session.
-
-#### Previous Session
-
-To view event telemetry from a previous session:
-
-1. Click the dropdown menu down arrow in the top left corner of `about:telemetry`
-2. Select 'Archived ping data'
-3. Select the `event` ping type
-4. Choose an archived `event` ping by date and time
-5. In the sidebar menu, select 'Raw Payload'
-6. You should see the `payload` JSON object displayed with events listed in the `events` array