Bug 1693126 - Add telemetry for when users disable Quick Suggest. r=harry,nanj

This adds event telemetry that's recorded when the
`browser.urlbar.suggest.quicksuggest` pref is toggled. This pref corresponds to
the checkbox in about:preferences#search labeled "Show suggested and sponsored
results in the address bar".

I used `contextservices.quicksuggest` as the event telemetry category name to be
similar to the `contextual.services.quicksuggest.*` scalars. Event names are
limited to 30 chars, so it couldn't be exactly the same.

This is based on my earlier revision for scalar telemetry in D106173.

Depends on D106173

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

browser/components/urlbar/UrlbarProviderQuickSuggest.jsm

@@ -19,8 +19,12 @@ XPCOMUtils.defineLazyModuleGetters(this, {
   UrlbarUtils: "resource:///modules/UrlbarUtils.jsm",
 });
 
+// These prefs are relative to the `browser.urlbar` branch.
+const EXPERIMENT_PREF = "quicksuggest.enabled";
+const SUGGEST_PREF = "suggest.quicksuggest";
 const ONBOARDING_COUNT_PREF = "quicksuggest.onboardingCount";
 const ONBOARDING_MAX_COUNT_PREF = "quicksuggest.onboardingMaxCount";
+
 const ONBOARDING_TEXT = "Learn more about Firefox Suggests";
 
 const TELEMETRY_SCALAR_IMPRESSION =
@@ -28,13 +32,18 @@ const TELEMETRY_SCALAR_IMPRESSION =
 const TELEMETRY_SCALAR_CLICK = "contextual.services.quicksuggest.click";
 const TELEMETRY_SCALAR_HELP = "contextual.services.quicksuggest.help";
 
+const TELEMETRY_EVENT_CATEGORY = "contextservices.quicksuggest";
+
 /**
  * A provider that returns a suggested url to the user based on what
  * they have currently typed so they can navigate directly.
  */
 class ProviderQuickSuggest extends UrlbarProvider {
-  // Whether we added a result during the most recent query.
-  _addedResultInLastQuery = false;
+  constructor(...args) {
+    super(...args);
+    this._updateExperimentState();
+    UrlbarPrefs.addObserver(this);
+  }
 
   /**
    * Returns the name of this provider.
@@ -73,8 +82,8 @@ class ProviderQuickSuggest extends UrlbarProvider {
     return (
       queryContext.trimmedSearchString &&
       !queryContext.searchMode &&
-      UrlbarPrefs.get("quicksuggest.enabled") &&
-      UrlbarPrefs.get("suggest.quicksuggest") &&
+      UrlbarPrefs.get(EXPERIMENT_PREF) &&
+      UrlbarPrefs.get(SUGGEST_PREF) &&
       UrlbarPrefs.get("suggest.searches") &&
       UrlbarPrefs.get("browser.search.suggest.enabled") &&
       (!queryContext.isPrivate ||
@@ -189,6 +198,44 @@ class ProviderQuickSuggest extends UrlbarProvider {
     }
   }
 
+  /**
+   * Called when a urlbar pref changes.  We use this to listen for changes to
+   * `browser.urlbar.suggest.quicksuggest` so we can record a telemetry event.
+   * We also need to listen for `browser.urlbar.quicksuggest.enabled` so we can
+   * enable/disable the event telemetry.
+   *
+   * @param {string} pref
+   *   The name of the pref relative to `browser.urlbar`.
+   */
+  onPrefChanged(pref) {
+    switch (pref) {
+      case EXPERIMENT_PREF:
+        this._updateExperimentState();
+        break;
+      case SUGGEST_PREF:
+        Services.telemetry.recordEvent(
+          TELEMETRY_EVENT_CATEGORY,
+          "enable_toggled",
+          UrlbarPrefs.get(SUGGEST_PREF) ? "enabled" : "disabled"
+        );
+        break;
+    }
+  }
+
+  /**
+   * Updates state based on the `browser.urlbar.quicksuggest.enabled` pref.
+   * Right now we only need to enable/disable event telemetry.
+   */
+  _updateExperimentState() {
+    Services.telemetry.setEventRecordingEnabled(
+      TELEMETRY_EVENT_CATEGORY,
+      UrlbarPrefs.get(EXPERIMENT_PREF)
+    );
+  }
+
+  // Whether we added a result during the most recent query.
+  _addedResultInLastQuery = false;
+
   get _onboardingCount() {
     return UrlbarPrefs.get(ONBOARDING_COUNT_PREF);
   }

browser/components/urlbar/docs/telemetry.rst

@@ -506,6 +506,25 @@ contextual.services.quicksuggest.*
       Incremented when the user picks the onboarding help button in a Quick
       Suggest result.
 
+contextservices.quicksuggest
+  This is event telemetry under the ``contextservices.quicksuggest`` category.
+  It's enabled only when the ``browser.urlbar.quicksuggest.enabled`` pref is
+  true. An event is recorded when the user toggles the
+  ``browser.urlbar.suggest.quicksuggest`` pref, which corresponds to the
+  checkbox in about:preferences#search labeled "Show suggested and sponsored
+  results in the address bar". If the user never toggles the pref, then this
+  event is never recorded.
+
+  The full spec for this event is:
+
+    - Category: ``contextservices.quicksuggest``
+    - Method: ``enable_toggled``
+    - Objects: ``enabled``, ``disabled`` -- ``enabled`` is recorded when the
+      pref is flipped from false to true, and ``disabled`` is recorded when the
+      pref is flipped from true to false.
+    - Value: Not used
+    - Extra: Not used
+
 Obsolete probes
 ---------------
 

browser/components/urlbar/tests/browser/browser_urlbar_telemetry_quicksuggest.js

@@ -32,6 +32,10 @@ const TELEMETRY_SCALARS = {
   HELP: "contextual.services.quicksuggest.help",
 };
 
+const TELEMETRY_EVENT_CATEGORY = "contextservices.quicksuggest";
+
+const EXPERIMENT_PREF = "browser.urlbar.quicksuggest.enabled";
+const SUGGEST_PREF = "suggest.quicksuggest";
 const ONBOARDING_COUNT_PREF = "quicksuggest.onboardingCount";
 
 add_task(async function init() {
@@ -39,7 +43,7 @@ add_task(async function init() {
   await UrlbarTestUtils.formHistory.clear();
   await SpecialPowers.pushPrefEnv({
     set: [
-      ["browser.urlbar.quicksuggest.enabled", true],
+      [EXPERIMENT_PREF, true],
       ["browser.urlbar.quicksuggest.helpURL", TEST_HELP_URL],
       ["browser.urlbar.suggest.searches", true],
     ],
@@ -220,6 +224,38 @@ add_task(async function help_mouse() {
   });
 });
 
+// Tests the contextservices.quicksuggest enable_toggled event telemetry by
+// toggling the suggest.quicksuggest pref.
+add_task(async function enableToggled() {
+  Services.telemetry.clearEvents();
+
+  // Toggle the suggest.quicksuggest pref twice.  We should get two events.
+  let enabled = UrlbarPrefs.get(SUGGEST_PREF);
+  for (let i = 0; i < 2; i++) {
+    enabled = !enabled;
+    UrlbarPrefs.set(SUGGEST_PREF, enabled);
+    TelemetryTestUtils.assertEvents([
+      {
+        category: TELEMETRY_EVENT_CATEGORY,
+        method: "enable_toggled",
+        object: enabled ? "enabled" : "disabled",
+      },
+    ]);
+  }
+
+  // Set the main quicksuggest.enabled pref to false and toggle the
+  // suggest.quicksuggest pref again.  We shouldn't get any events.
+  await SpecialPowers.pushPrefEnv({
+    set: [[EXPERIMENT_PREF, false]],
+  });
+  enabled = !enabled;
+  UrlbarPrefs.set(SUGGEST_PREF, enabled);
+  TelemetryTestUtils.assertEvents([], { category: TELEMETRY_EVENT_CATEGORY });
+  await SpecialPowers.popPrefEnv();
+
+  UrlbarPrefs.clear(SUGGEST_PREF);
+});
+
 /**
  * Checks the values of all the Quick Suggest scalars.
  *

toolkit/components/telemetry/Events.yaml

@@ -2720,3 +2720,18 @@ installation:
       - agashlin@mozilla.com
       - rtestard@mozilla.com
     expiry_version: "94"
+
+contextservices.quicksuggest:
+  enable_toggled:
+    objects: ["enabled", "disabled"]
+    release_channel_collection: opt-out
+    products:
+      - "firefox"
+    record_in_processes: ["main"]
+    description: >
+      This is recorded when the `browser.urlbar.suggest.quicksuggest` boolean
+      pref is toggled.
+    bug_numbers: [1693126]
+    notification_emails:
+      - fx-search@mozilla.com
+    expiry_version: never