Skip to content
This repository has been archived by the owner on Oct 14, 2020. It is now read-only.

Latest commit

 

History

History
105 lines (67 loc) · 4.5 KB

README.md

File metadata and controls

105 lines (67 loc) · 4.5 KB
Raw
WebExtensions API:s Engineering your add-on

Shield Studies Add-on Utils

CircleCI badge

Features

This is the home of the shield-studies-addon-utils npm package, which provides:

shield-study telemetry

Validate and send shield-study, shield-study-addon Telemetry, allowing experiments to submit experiment-scoped stringified key-value pairs that are directly available for analysis.

Pioneer telemetry

Validate, encrypt and send shield-study, shield-study-addon Pioneer Telemetry.

Other telemetry helpers

Validate telemetry payloads against JSON schemas and calculate the size of a ping before submitting it.

Add-on test helpers

Helper classes and methods to write Selenium-based functional/unit tests for your study add-on.

Survey URLs helper

For formatting 'post' and 'mid-study' survey URLs to have correct appended query arguments in the format that matches the corresponding SurveyGizmo library elements

Help and support

Thinking about building a Study Add-on? Please read the docs on Pref-Flip and Add-On Experiments first.

Installing Shield Studies Add-on Utils in your add-on

npm install --save shield-studies-addon-utils
  • Run copyStudyUtils yourAddonSrc/privileged/ which copies webExtensionApis/study/api.js and webExtensionApis/study/schema.json to your add-on's source directory under yourAddonSrc/privileged/study,
  • add the following to your add-on's manifest.json:
  "experiment_apis": {
    "study": {
      "schema": "./privileged/study/schema.json",
      "parent": {
        "scopes": ["addon_parent"],
        "script": "./privileged/study/api.js",
        "paths": [["study"]]
      }
    }
  },

WebExtension APIs Provided by Shield Studies Add-on Utils

browser.study.*

browser.study API documentation

Supported telemetry pipelines

Depending on which telemetry pipeline is used, the pings end up in different destinations:

  • shield - The pings end up in the shield-study and shield-study-addon Telemetry buckets for instant access to submitted payloads via STMO.
  • pioneer - The pings are encrypted and end up in the Pioneer processing pipeline.
  • TODO: event-telemetry - The pings end up in the ordinary destination for event telemetry (Not Yet Implemented)

browser.studyDebug.*

browser.studyDebug API documentation

Used by the project-internal tests only.

Engineering your own study add-on

Development on the Shield-Studies-Addon-Utils

History of recent major versions

  • v6.0: Rip out most functionality, keeping only some high priority utils* that neither the Normandy WebExtension API nor the Nextgen study example provides
  • v5.3: Better study endings and browser.study.fullSurveyUrl()
  • v5.2: Added Pioneer and Firefox 67 support
  • v5.1: Added preferences for testing overrides, study logger and other enhancements
  • v5: API exposed as a Web Extension Experiment. Minimal viable add-on example added. Test coverage improved. Test utils added.

* Some features that was handled in v5 has not been ported over to neither Normandy nor v6 of the utils:

  • expiry
  • lifecycle telemetry (first seen, installed, exit etc)
  • configurable endings (annotated exit telemetry and launching of exit surveys etc)
  • telemetry testing flag specific to study telemetry (disable telemetry via about:config during testing instead)
  • pref-controlled study-specific study logger (use ordinary add-on-scoped logging instead)