npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

shield-studies-addon-utils

v6.0.0

Published

Utilities for Mozilla Firefox study add-ons.

Downloads

21

Readme

| 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)