BrowserUsageTelemetry.rst (7334B)
1 .. _browserusagetelemetry: 2 3 ======================= 4 Browser Usage Telemetry 5 ======================= 6 7 The `BrowserUsageTelemetry.sys.mjs <https://searchfox.org/mozilla-central/source/browser/modules/BrowserUsageTelemetry.sys.mjs>`_ module is the main module for measurements regarding the browser usage (e.g. tab and window counts, search counts, ...). 8 9 The measurements recording begins right after the ``SessionStore`` has finished restoring the session (i.e. restoring tabs/windows after Firefox starts). 10 11 Tab and window interactions 12 =========================== 13 The usage telemetry module currently measures these interactions with the browser's tabs and windows: 14 15 - *tab and window engagement*: counts the number of non-private tabs and windows opened in a subsession, after the session is restored (see e.g. ``browser.engagement.max_concurrent_tab_count``); 16 - *URI loads*: counts the number of page loads (doesn't track and send the addresses, just the counts) directly triggered by the users (see ``browser.engagement.total_uri_count``); 17 - *navigation events*: at this time, this only counts the number of time a page load is triggered by a particular UI interaction (e.g. by searching through the URL bar, see ``browser.engagement.navigation.urlbar``). 18 19 20 Please see `Scalars.yaml <https://searchfox.org/mozilla-central/source/toolkit/components/telemetry/Scalars.yaml>`_ for the full list of tracked interactions. 21 22 Customizable UI 23 =============== 24 25 This telemetry records information about the positions of toolbar items and when 26 the user interacts with them. It is submitted as scalar values along with the 27 normal telemetry ping. There are a number of different parts to this telemetry: 28 29 UI Areas 30 -------- 31 32 For the purposes of this telemetry a set of areas are defined: 33 34 * In the main browser UI: 35 36 * ``menu-bar`` - The main menu. 37 * ``menu-toolbar`` - The normally hidden toolbar that holds the main menu. 38 * ``titlebar`` - The optional title bar. 39 * ``tabs-bar`` - The area where tabs are displayed. 40 * ``vertical-tabs-container`` - The area where vertical tabs are displayed. 41 * ``bookmarks-bar`` - The bookmarks toolbar. 42 * ``app-menu`` - The main application (hamburger) menu. 43 * ``tabs-context`` - The context menu shown from right-clicking a tab. 44 * ``content-context`` - The context menu shown from right-clicking the web page. 45 * ``widget-overflow-list`` - Items that have overflowed the available space. 46 * ``pinned-overflow-menu`` - Items that the user has pinned to the toolbar overflow menu. 47 * ``pageaction-urlbar`` - Page actions buttons in the address bar. 48 * ``pageaction-panel`` - The page action (meatball) menu. 49 * ``nav-bar-start`` - The area of the navigation toolbar before the address bar. 50 * ``nav-bar-end`` - The area of the navigastion toolbar after the address bar. 51 * ``unified-extensions-area`` - The unified extensions panel. 52 53 * In ``about:preferences`` the different cagtegories are used: 54 55 * ``preferences-paneGeneral`` 56 * ``preferences-paneHome`` 57 * ``preferences-panePrivacy`` 58 * ``preferences-paneSearch`` 59 * ``preferences-paneSearchResults`` 60 * ``preferences-paneSync`` 61 * ``preferences-paneContainers`` 62 63 Widget Identifiers 64 ------------------ 65 66 In order to uniquely identify a visual element a set of heuristics are used: 67 68 #. If the element is one of the customizable toolbar items then that item's ID 69 is used. 70 #. If the DOM element has an ID set then that is used. 71 #. If the DOM element's class contains one of ``bookmark-item``, 72 ``tab-icon-sound`` or ``tab-close-button`` then that is used. 73 #. If the DOM element has a ``preference`` ``key``, ``command``, ``observes`` or 74 ``data-l10n-id`` attribute then that is used. 75 #. If there is still no identifier then this is repeated for the DOM element's 76 parent element. 77 78 Widget Locations 79 ---------------- 80 81 The keyed scalar ``browser.ui.toolbar_widgets`` records the position of widgets in 82 the UI. At startup the positions of widgets are collected and recorded by 83 setting the scalar key ``<widget id>_pinned_<area>`` to true. The widget ID are 84 the IDs of the elements in the DOM. The area is one of the areas listed above 85 from the browser UI that can be customised. 86 87 For the areas that can be controlled the scalar keys ``<area>_<off/on/newtab>`` are set. 88 ``newtab`` is special to the Bookmarks Toolbar and is used when the toolbar will only 89 be shown on the New Tab page. 90 91 Widget Customization 92 -------------------- 93 94 The scalar ``browser.ui.customized_widgets`` records whenever the user moves a 95 widget around the toolbars or shows or hides some of the areas. When a change 96 occurs the scalar with the key ``<widget id>_<action>_<old area>_<new area>_<reason>`` 97 is incremented. The action can be one of ``move``, ``add`` or ``remove``. Old 98 area and new area are the previous and now locations of the widget. In the case 99 of ``add`` or ``remove`` actions one of the areas will be ``na``. For areas that 100 can be shown or hidden the areas will be ``off`` or ``on``. The reason is a simple 101 string that indicates what caused the move to happen (drag, context menu, etc.). 102 103 UI Interactions 104 --------------- 105 106 The scalars ``browser.ui.interaction.<area>`` record how often the use 107 interacts with the browser. The area is one of those above with the addition of 108 ``keyboard`` for keyboard shortcuts. 109 110 When an interaction occurs the widget's identifier is used as the key and the 111 scalar is incremented. If the widget is provided by an add-on then the add-on 112 identifier is dropped and an identifier of the form ``addonX`` is used where X 113 is a number. The number used is stable for a single session. Every time the user 114 moves or interacts with an add-on the same number is used but then the numbers 115 for each add-on may change after Firefox has been restarted. 116 117 Profile Count 118 ============= 119 120 The scalar ``browser.engagement.profile_count`` records how many profiles have 121 been used by the current Firefox installation. It reports a bucketed result, 122 which will be 0 if there is an error. The raw value will be reported for 1-10, 123 but above that, it will report 10 for 10-99, 100 for 100-999, 1000 for 124 1000-9999, and 10000 for any values greater than that. 125 126 The profile count data for an installation is stored in the root of the 127 update directory in a file called ``profile_count_<install hash>.json``. The 128 full path to the file will typically look something like 129 ``C:\ProgramData\Mozilla\profile_count_5A9E6E2F272F7AA0.json``. 130 131 This value is meant to be resilient to re-installation, so that file will not 132 be removed when Firefox is uninstalled. 133 134 Context menu entrypoints 135 ======================== 136 137 Some context menus are re-used in multiple places. By default, we simply count 138 the number of interactions per item within a context menu, and do not record 139 the entrypoint that caused the context menu to open. 140 141 It is possible to opt-in to recording the entrypoint that caused the context 142 menu to open. This is done by adding an entry to 143 ``ENTRYPOINT_TRACKED_CONTEXT_MENU_IDS``, mapping the ID of the context menu 144 to a keyed Scalar under ``browser.ui.interaction.``. This scalar is recorded 145 only if an interaction is recorded within the context menu itself. 146 147 When the keyed scalar is recorded, the key will be a unique ID for the 148 trigger node that caused the context menu to open. The value is the count 149 of openings from that trigger node.