Default Search Engines

Default Engine

The search service specifies default search engines via the configuration schema.

Changing Defaults

The default engine may change when:

  • The user has the default engine set and the configuration for the locale/region changes.

  • The user has the default engine set and their locale/region changes to one which has a different default.

  • The user chooses to set a different engine via preferences.

  • The user installs an add-on which sets its default as one of the application provided engines.

  • The user installs an add-on which supplies a different engine and the user allows the different engine to be set as default.

  • The user or Firefox (e.g. via blocklist) causes the default engine to be removed.

Add-ons and Prompting for Default

The prompt for selecting a search engine from an add-on as default is shown to the user on installation of the add-on. It may also be shown if an add-on is re-enabled, if the default engine was not changed in the meantime.

The following diagram shows the full flow for search engines from add-ons:

Flowchart for prompting for default engine for Search Engines related to add-ons.

When the Default Engine is Removed

If the default engine is removed by the user, or by Firefox in the case of a blocklist or for some other region, the new default engine is chosen by the following process.

  • If the default engine specified by the configuration for the user’s region and locale is visible, then it will be selected as default.

  • If there is another engine visible, fall back to the first engine identified as a general search engine (see below).

  • If there are no other visible engines, unhide the region/locale default engine from the configuration and set it as default if it is not the one being removed.

  • Otherwise, unhide the first general search engine, or the first visible engine.

A general search engine is defined as one that returns general search results, for example Google or DuckDuckGo. A non-general search engine returns results for a specific area, e.g. shopping, books, dictionaries.

Add-ons and App-provided Engines

An add-on may set the name of the search provider in the manifest.json to be the name of an app-provided engine. In this case:

  • If the add-on is a non-authorised partner, then we set the user’s default engine to be the name of the app-provided engine.

  • If the add-on is from an authorised partner, then we set the users’ default engine to be the same as the app-provided engine, and we allow the app-provided urls to be overridden with those of the add-on.

If the specified engine is already default, then the add-on does not override the app-provided engine, and it’s settings are ignored and no new engine is added.

The list of authorised add-ons is stored in remote settings in the search-default-override-allowlist bucket. The list includes records containing:

  • Third-party Add-on Id: The identifier of the third party add-on which will override the app provided one.

  • Add-on Id to Override: The identifier of the app-provided add-on to be overridden.

  • a list of the url / params that are authorised to be replaced.

When an authorised add-on overrides the default, we record the add-on’s id with the app-provided engine in the overriddenBy field. This is used when the engine is loaded on startup to known that it should load the parameters from that add-on.

The overriddenBy annotation may be removed when:

  • The associated authorised add-on is removed, disabled or can no longer be found.

  • The user changes their default to another engine.

If the overriddenBy annotation is present, but the add-on is not authorised, then the annotation will be maintained in case the add-on is later re-authorised. For example, a url is updated, but the update is performed before the allow list is updated.