summaryrefslogtreecommitdiffstats
path: root/browser/components/search/docs
diff options
context:
space:
mode:
Diffstat (limited to 'browser/components/search/docs')
-rw-r--r--browser/components/search/docs/Preferences.rst25
-rw-r--r--browser/components/search/docs/application-search-engines.rst41
-rw-r--r--browser/components/search/docs/index.rst23
-rw-r--r--browser/components/search/docs/telemetry.rst201
4 files changed, 290 insertions, 0 deletions
diff --git a/browser/components/search/docs/Preferences.rst b/browser/components/search/docs/Preferences.rst
new file mode 100644
index 0000000000..ca379ed712
--- /dev/null
+++ b/browser/components/search/docs/Preferences.rst
@@ -0,0 +1,25 @@
+Preferences
+===========
+
+This document describes preferences affecting Firefox's Search UI code. For information
+on the toolkit search service, see the :doc:`/toolkit/search/Preferences` document.
+Preferences that are generated and updated by code won't be described here.
+
+User Exposed
+------------
+These preferences are exposed through the Firefox UI
+
+browser.search.widget.inNavBar (boolean, default: false)
+ Whether the search bar widget is displayed in the navigation bar.
+
+Hidden
+------
+These preferences are normally hidden, and should not be used unless you really
+know what you are doing.
+
+browser.search.openintab (boolean, default: false)
+ Whether or not items opened from the search bar are opened in a new tab.
+
+browser.search.context.loadInBackground (boolean, default: false)
+ Whether or not tabs opened from searching in the context menu are loaded in
+ the foreground or background.
diff --git a/browser/components/search/docs/application-search-engines.rst b/browser/components/search/docs/application-search-engines.rst
new file mode 100644
index 0000000000..30bc0b7575
--- /dev/null
+++ b/browser/components/search/docs/application-search-engines.rst
@@ -0,0 +1,41 @@
+Application Search Engines
+==========================
+
+Firefox defines various application search engines that are shipped to users.
+
+The extensions for the definitions of these engines live in
+:searchfox:`browser/components/search/extensions <browser/components/search/extensions>`
+
+Icons
+-----
+
+Icon Requirements
+~~~~~~~~~~~~~~~~~
+
+It is preferred that each engine is shipped with a ``.ico`` file with two sizes
+of image contained within the file:
+
+ * 16 x 16 pixels
+ * 32 x 32 pixels
+
+Some engines also have icons in
+:searchfox:`browser/components/newtab/data/content/tippytop <browser/components/newtab/data/content/tippytop>`.
+For these engines, there are two sizes depending on the subdirectory:
+
+ * ``favicons/``: 32 x 32 pixels
+ * ``images/``: preferred minimum of 192 x 192 pixels
+
+Updating Icons
+~~~~~~~~~~~~~~
+
+To update icons for application search engines:
+
+ * Place the new icon file in the :searchfox:`folder associated with the search engine <browser/components/search/extensions>`.
+ * Increase the version number in the associated manifest file. This ensures
+ that the add-on manager properly updates the engine.
+ * Be aware that the :searchfox:`allowed-dupes.mn file <browser/installer/allowed-dupes.mn>`
+ lists some icons that are intended as duplicates.
+
+To update icons for tippytop:
+
+ * Place the new icon file in :searchfox:`both the sub-folders within the tippytop directory <browser/components/newtab/data/content/tippytop>`.
diff --git a/browser/components/search/docs/index.rst b/browser/components/search/docs/index.rst
new file mode 100644
index 0000000000..a608a12876
--- /dev/null
+++ b/browser/components/search/docs/index.rst
@@ -0,0 +1,23 @@
+Search
+======
+
+This document describes the implementation of parts of Firefox's search interfaces.
+
+The search area covers:
+
+ * Search bar on the toolbar
+ * In-content search
+ * One-off search buttons on both the search and address bars
+
+Search Engine handling is taken care of with the `toolkit Search Service`_.
+
+Most of the search code lives in `browser/components/search`_.
+
+.. toctree::
+
+ application-search-engines
+ Preferences
+ telemetry
+
+.. _toolkit Search Service: /toolkit/search/index.html
+.. _browser/components/search: https://searchfox.org/mozilla-central/source/browser/components/search
diff --git a/browser/components/search/docs/telemetry.rst b/browser/components/search/docs/telemetry.rst
new file mode 100644
index 0000000000..bbf67aa68f
--- /dev/null
+++ b/browser/components/search/docs/telemetry.rst
@@ -0,0 +1,201 @@
+Telemetry
+=========
+
+This section describes existing telemetry probes measuring interaction with
+search engines from the browser UI.
+
+Other search-related telemetry is recorded by Toolkit such as search service
+telemetry and telemetry related to fetching search suggestions. Toolkit search
+telemetry is relevant to Firefox as well as other consumers of Toolkit. See
+:doc:`/toolkit/search/Telemetry` in the Toolkit documentation for details.
+
+.. contents::
+ :depth: 2
+
+
+Glossary
+--------
+
+SAP
+ Search Access Point, a search that a user performs by visiting
+ via one of Firefox's access points using the associated partner codes.
+
+SERP
+ A search engine results page.
+
+Persisted Search
+ When a user has the following preference values:
+
+ - ``browser.urlbar.showSearchTerms.enabled``: ``true``
+ - ``browser.urlbar.showSearchTerms.featureGate``: ``true``
+ - ``browser.search.widget.inNavBar``: ``false``
+
+ and does the following:
+
+ - Starts a search from the urlbar or context menu.
+ - Loads the default search engine results page.
+
+ the search term will persist in the Urlbar, causing it to enter a Persisted Search state.
+
+.. _serp-definitions:
+
+Definitions
+-----------
+
+``organic``
+ A search that a user performs by visiting a search engine directly.
+
+``tagged``
+ Refers to a page that is tagged with an associated partner code.
+ It may or may not have originated via a SAP.
+
+``tagged-follow-on``
+ Refers to a page that is tagged with an associated partner code and has been identified
+ as a follow-on search. It may or may not have originated via a SAP.
+
+Search probes relevant to front-end searches
+--------------------------------------------
+
+The Address Bar is an integral part of search and has `additional telemetry of its own`_.
+
+BrowserSearchTelemetry.sys.mjs
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This telemetry is handled by `BrowserSearchTelemetry.sys.mjs`_.
+
+SEARCH_COUNTS - SAP usage
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+ This histogram tracks search engines and Search Access Points. It is augmented
+ by multiple SAPs, including the urlbar.
+ It's a keyed histogram, the keys are strings made up of search engine names
+ and SAP names, for example ``google.urlbar``.
+ For each key, this records the count of searches made using that engine and SAP.
+ SAP names can be:
+
+ - ``alias`` This is when using an alias (like ``@google``) in the urlbar.
+ Note there is often confusion between the terms alias and keyword, and
+ they may be used inappropriately: aliases refer to search engines, while
+ keywords refer to bookmarks. We expect no results for this SAP in Firefox
+ 83+, since urlbar-searchmode replaces it.
+ - ``abouthome``
+ - ``contextmenu``
+ - ``newtab``
+ - ``searchbar``
+ - ``system``
+ - ``urlbar`` Except aliases and search mode.
+ - ``urlbar-handoff`` Used when searching from about:newtab.
+ - ``urlbar-persisted`` Used when searching from the Urlbar while it
+ was in a Persisted Search state.
+ - ``urlbar-searchmode`` Used when the Urlbar is in search mode.
+ - ``webextension``
+
+browser.engagement.navigation.*
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+ These keyed scalars track search through different SAPs, for example the
+ urlbar is tracked by ``browser.engagement.navigation.urlbar``.
+ It counts loads triggered in a subsession from the specified SAP, broken down
+ by the originating action.
+ Possible SAPs are:
+
+ - ``urlbar`` Except search mode.
+ - ``urlbar_handoff`` Used when searching from about:newtab.
+ - ``urlbar_persisted`` Used when searching from the Urlbar while it
+ was in a Persisted Search state.
+ - ``urlbar_searchmode`` Used when the Urlbar is in search mode.
+ - ``searchbar``
+ - ``about_home``
+ - ``about_newtab``
+ - ``contextmenu``
+ - ``webextension``
+ - ``system`` Indicates a search from the command line.
+
+ Recorded actions may be:
+
+ - ``search``
+ Used for any search from ``contextmenu``, ``system`` and ``webextension``.
+ - ``search_alias``
+ For ``urlbar``, indicates the user confirmed a search through an alias.
+ - ``search_enter``
+ For ``about_home`` and ``about:newtab`` this counts any search.
+ For the other SAPs it tracks typing and then pressing Enter.
+ - ``search_formhistory``
+ For ``urlbar``, indicates the user picked a form history result.
+ - ``search_oneoff``
+ For ``urlbar`` or ``searchbar``, indicates the user confirmed a search
+ using a one-off button.
+ - ``search_suggestion``
+ For ``urlbar`` or ``searchbar``, indicates the user confirmed a search
+ suggestion.
+
+navigation.search (OBSOLETE)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+ This is a legacy and disabled event telemetry that is currently under
+ discussion for removal or modernization. It can't be enabled through a pref.
+ it's more or less equivalent to browser.engagement.navigation, but can also
+ report the picked search engine.
+
+SearchSERPTelemetry.sys.mjs
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This telemetry is handled by `SearchSERPTelemetry.sys.mjs and the associated parent/child actors`_.
+
+browser.search.content.*
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+ These keyed scalars track counts of SERP page loads.
+
+ The key format is ``<provider>:[tagged|tagged-follow-on|organic]:[<code>|other|none]``.
+ The values in angled brackets will be replaced by real values based on the URL of the
+ SERP page. The key format is built from:
+
+ - ``<provider>`` The name of the provider. This is not linked to search engine
+ ids, as the search may have been generated organically.
+ - ``[tagged|tagged-follow-on|organic]`` The type of SERP load. See the
+ :ref:`definitions section above <serp-definitions>`.
+ - ``[<code>|other|none]`` Details of the code associated with the SERP load:
+
+ - ``<code>`` The partner code found in the URL. This is only for partners
+ associated with the product.
+ - ``other`` The SERP load had a partner code, but it is not recognised as
+ an associated partner or an organic code.
+ - ``none`` The SERP load had no partner codes, or it was a recognised organic code,
+ e.g. some sites assign their own codes for searches.
+
+ They are broken down by the originating SAP where known:
+
+ - ``urlbar`` Except search mode.
+ - ``urlbar_handoff`` Used when searching from about:newtab.
+ - ``urlbar_persisted`` Used when searching from the Urlbar while it
+ was in a Persisted Search state.
+ - ``urlbar_searchmode`` Used when the Urlbar is in search mode.
+ - ``searchbar``
+ - ``about_home``
+ - ``about_newtab``
+ - ``contextmenu``
+ - ``webextension``
+ - ``system`` Indicates a search from the command line.
+ - ``tabhistory`` Indicates a search was counted as a result of the user loading it from the tab history.
+ - ``reload`` Indicates a search was counted as a result of reloading the page.
+ - ``unknown`` Indicates the origin was unknown.
+
+browser.search.withads.*
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+ These keyed scalar track counts of SERP pages with adverts displayed. The key
+ format is ``<provider>:<tagged|organic>``.
+
+ They are broken down by the originating SAP where known, the list of SAP
+ is the same as for ``browser.search.content.*``.
+
+browser.search.adclicks.*
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+ This is the same as ```browser.search.withads.*`` but tracks counts for them
+ clicks of adverts on SERP pages.
+
+.. _additional telemetry of its own: /browser/urlbar/telemetry.html
+.. _SearchSERPTelemetry.sys.mjs and the associated parent/child actors: https://searchfox.org/mozilla-central/search?q=&path=SearchSERPTelemetry*.sys.mjs&case=false&regexp=false
+.. _BrowserSearchTelemetry: https://searchfox.org/mozilla-central/source/browser/components/search/BrowserSearchTelemetry.sys.mjs