174 lines
8.7 KiB
ReStructuredText
174 lines
8.7 KiB
ReStructuredText
==============
|
||
Search Engines
|
||
==============
|
||
This document describes the four main type of search engines the IceCat
|
||
serves to the user, enabling users to search the internet with different
|
||
search providers. The types of search engines are:
|
||
|
||
- Application Provided Search Engines
|
||
- Add-on Search Engines
|
||
- Open Search Engines
|
||
- Enterprise Policy Engines
|
||
|
||
These are all represented by `similarly named classes`_ which inherit from
|
||
the ``SearchEngine`` class and implement the :searchfox:`nsISearchEngine.idl <toolkit/components/search/nsISearchService.idl>`
|
||
interface.
|
||
|
||
Application Provided Search Engines
|
||
===================================
|
||
Application Provided Search Engines are engines provided by the application to
|
||
the user as part of the configuration for the user's locale and region.
|
||
These engines are managed through the `Search Configuration`_ file hosted on Remote Settings.
|
||
|
||
Add-on Search Engines
|
||
=====================
|
||
Users can install Add-on Search Engines into IceCat. Add-ons are additional
|
||
functionality that third-party developers provide for users.
|
||
|
||
To define Add-on Search Engines, developers use the `WebExtensions API`_,
|
||
specifically the `chrome_settings_overrides`_ manifest key.
|
||
|
||
Since the WebExtensions API technology is used, developers interchangeably used
|
||
the term WebExtension Search Engines when referring to Add-ons Search Engines.
|
||
|
||
|
||
In Practice
|
||
-----------
|
||
All versions of IceCat support add-ons. IceCat switched over from OpenSearch
|
||
to Add-on Search Engines internally in IceCat version 78. We no longer ship
|
||
Application Provided Search Engines through web extensions and switched to
|
||
managing these engines via Remote Settings in IceCat version 126,
|
||
as of April 22, 2024.
|
||
|
||
OpenSearch Engines
|
||
===================
|
||
OpenSearch is a plugin, software installed on IceCat to enhance capabilities
|
||
for searching. OpenSearch has a collection of formats that describe how to
|
||
construct the url, images, strings, icon, etc. These formats provided by
|
||
OpenSearch allow IceCat to make a search over the internet with a specific
|
||
search provider that is not an application provided search engine on IceCat.
|
||
The purpose of OpenSearch is to provide more convenient ways of searching and
|
||
different ways of searching.
|
||
|
||
OpenSearch allows users to search with a vast variety of search providers which
|
||
do not come installed with IceCat out of the box. The main benefit of OpenSearch
|
||
is it allows site owners to easily provide users with a way to search a site.
|
||
|
||
History
|
||
-------
|
||
Prior to OpenSearch, search plugins were first created by the `Mycroft Project`_
|
||
and based off of `Sherlock`_, a file and web search
|
||
tool created by Apple.
|
||
|
||
The OpenSearch Protocol was created and launched by A9.com in 2005. OpenSearch
|
||
was added to IceCat version 2 in the year 2006. As of today in 2022, OpenSearch
|
||
is a collection of formats for sharing of search results. The code is stable but
|
||
unchanged for many years.
|
||
|
||
See the `OpenSearch Documentation`_ for more information on the OpenSearch formats.
|
||
|
||
Autodiscovery
|
||
-------------
|
||
Autodiscovery is a feature on IceCat which automatically notifies the user when
|
||
the webpage they visited has a search plugin.
|
||
|
||
Here is an example of Autodiscovery from Bugzilla. You can visit
|
||
https://bugzilla.mozilla.org and IceCat will automatically detect that the
|
||
website has a provided search plugin. In the results dropdown, you can look at
|
||
the search engine shortcuts section at the bottom and it will show a green plus
|
||
sign over the Bugzilla search icon. The green plus sign indicates that the user
|
||
can add Bugzilla as an OpenSearch Engine. After the user adds Bugzilla as an
|
||
OpenSearch Engine, the green plus icon disappears. The user can now click the
|
||
Bugzilla icon to make a search directly on bugzilla.mozilla.org.
|
||
|
||
.. figure:: assets/bugzilla-open-search1.png
|
||
:alt: Image of the address bar input showing a URL
|
||
:scale: 28%
|
||
:align: center
|
||
|
||
.. figure:: assets/bugzilla-open-search2.png
|
||
:alt: Image of the address bar input showing a URL
|
||
:scale: 28%
|
||
:align: center
|
||
|
||
See the `Autodiscovery MDN Documentation`_ for more information on Autodiscovery.
|
||
|
||
Enterprise Policy Engines
|
||
=========================
|
||
Enterprise Policies are customizable configurations for the IceCat browser set
|
||
by enterprises or companies who want to distribute configuration for their
|
||
users. The idea of Enterprise Policies is to allow companies to customize IceCat
|
||
and how their users can or cannot change the usage of IceCat based on predefined
|
||
configuration that was set in place.
|
||
|
||
Enterprise Policy Engines are search engines that a company has added as search
|
||
engines on IceCat for their users by setting the Enterprise Policy. In this
|
||
`Enterprise Policy Documentation`_ it outlines the different options that are
|
||
available for enterprises using IceCat ESR (Extended Support Release) and what’s
|
||
available in terms of adding, updating, or removing search engines. The company
|
||
can use the policy to define which search engines are available on their IceCat ESR.
|
||
|
||
See the `policy-templates`_ for more information on Enterprise Policy templates
|
||
and the different configuration rules available.
|
||
|
||
Configuration
|
||
-------------
|
||
In practice, there are different ways for a company to specify their policy,
|
||
depending on which operating system their machines are on. The admin can
|
||
configure the policy on a server and when the user logs in, those configurations
|
||
are automatically pushed to the user’s IceCat.
|
||
|
||
For Windows, the `GPO (Group Policy Object)`_ or `Intune (Microsoft Endpoint Manager)`_ is
|
||
used to set the policy. For macOS, `configuration profiles`_ are created.
|
||
For the generic case, there is a JSON file to describe the policy.
|
||
|
||
When these configurations are set, IceCat takes the configuration as inputs and
|
||
turns them into settings that IceCat can consume.
|
||
|
||
A Hypothetical Use of Enterprise Policy
|
||
---------------------------------------
|
||
A company that is in the banking industry and requires tighter security over
|
||
their users may not want their users to do something on IceCat without the
|
||
company's knowledge. It may make sense for the company to disable private
|
||
browsing for IceCat.
|
||
|
||
Within a specific company, the employees of the finance department could use the
|
||
IceCat ESR version. In this situation, we think of the finance department as
|
||
the IceCat user rather than the individual employees as IceCat users. The
|
||
department makes choices for the individuals that use the IceCat browser
|
||
through the Enterprise Policy.
|
||
|
||
Features On Enterprise Policy
|
||
-----------------------------
|
||
All IceCat versions have to honor the Enterprise Policy, but the Enterprise
|
||
Policy may not have effect on an individual who is not using IceCat ESR at a
|
||
company. There are features that are enterprise specific that are only available
|
||
in ESR. These features allow search engines to be configured, allowing for
|
||
unsigned extensions, installing search engines, and setting a default search
|
||
engine.
|
||
|
||
How To Set Up and Use an Enterprise Policy for IceCat
|
||
------------------------------------------------------
|
||
Install the ESR version of IceCat since Enterprise Policies are not supported on
|
||
rapid release. Then, create the JSON file that is located in the README.md within
|
||
https://github.com/mozilla/policy-templates. There are instructions there on how
|
||
to configure and use the policy. Once the JSON is created with the appropriate
|
||
settings, drop the JSON file in the directory outlined by the README.md and
|
||
IceCat will find it and IceCat will open and run with the policy.
|
||
|
||
Common formatting mistakes are often made when creating the JSON file. The JSON
|
||
file can be validated using a JSON validator such as https://jsonlint.com/.
|
||
|
||
.. _similarly named classes: https://searchfox.org/mozilla-central/search?q=&path=toolkit%2Fcomponents%2Fsearch%2F*SearchEngine.sys.mjs
|
||
.. _Search Configuration: SearchConfigurationSchema.html
|
||
.. _WebExtensions API: https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions
|
||
.. _chrome_settings_overrides: https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/chrome_settings_overrides
|
||
.. _Sherlock: https://en.wikipedia.org/wiki/Sherlock_(software)
|
||
.. _Mycroft Project: https://mycroftproject.com/
|
||
.. _OpenSearch Documentation: https://github.com/dewitt/opensearch
|
||
.. _Autodiscovery MDN Documentation: https://developer.mozilla.org/en-US/docs/Web/OpenSearch#autodiscovery_of_search_plugins
|
||
.. _Enterprise Policy Documentation: https://mozilla.github.io/policy-templates/#searchengines-this-policy-is-only-available-on-the-esr
|
||
.. _policy-templates: https://mozilla.github.io/policy-templates/
|
||
.. _GPO (Group Policy Object): https://github.com/mozilla/policy-templates/tree/master/windows
|
||
.. _Intune (Microsoft Endpoint Manager): https://support.mozilla.org/en-US/kb/managing-icecat-intune
|
||
.. _configuration profiles: https://github.com/mozilla/policy-templates/tree/master/mac
|