-
Notifications
You must be signed in to change notification settings - Fork 3k
Search Engines in Fx IOS
This document gives an overview of how Firefox-iOS handles search engines for different locales. In short, an engine needs to be compliant and requested enough before it can be added to our app.
(Update 2/28/25) The information on this page will soon be outdated as we move towards Search Engine Consolidation (Jira epic) in the iOS client. This feature will leverage the shared search engine information on our Remote Settings servers to allow iOS to share the same logic and engine lists as Android and Desktop, and allow for easier updates to our search engine data. The iOS client will use Application Services APIs to fetch and sort search engine lists for the user's locale, rather than hardcoding this logic in the client. This will eventually obviate the need for the pre-bundled search engine XML files mentioned further below.
Firefox iOS will soon support consolidated search. This allows the client to utilize a cross-platform set of search engines (filtered for users based on their locale/region) that are supplied to us via the Application Services framework (part of our "Remote Settings"). There are several advantages to this approach versus our older method using pre-bundled XML engines (described further below), notably:
- The search engine data can be updated on-the-fly without requiring an app update
- Search engine data is now shared across all platforms (Android, iOS, Desktop)
- Search engines can be updated or modified much more quickly and easily
Consolidated Search is currently behind a feature flag (see isSECEnabled, SEC = Search Engine Consolidation). When enabled, we switch away from using our XML-based bundled engine data in favor of Application Services. Much of the higher-level architecture has been kept as-is, and in fact only a few key lower-level components that provide the engine data have been changed.
The client has new SearchEngineProvider conformer that is used by SearchEnginesManager when Consolidated Search is enabled. Rather than parse the XML and JSON files to determine search engine data, this new provider taps into the new APIs on the Application Services framework. We are provided a list of SearchEngineDefinitions.
In order to allow most of the existing code to work as-is, currently the Consolidated Search code converts these AS-based engines to our existing OpenSearchEngine model.
At this point we vend the OpenSearchEngines to the higher-level code in the client, which continues to work as is.
As part of the Consolidated Search update, our preferences management has also changed. We have moved away from persisting engine ordering preferences (defined by the user in their Settings) as a list of engine short names, and instead we now persist the engine ID. In order for this to work there is code to provide preferences migration between the two versions as needed.
When you begin typing a search query in the URLBar, you'll notice a couple things:
- Your default search engine is already set, unless you've changed it previously in settings.
- There might be a handful of search engines below. Tapping one will perform a search of your query with that engine.
Those engine choices were made for you according to what engines are "compliant" in your locale.
Search engine compliance for a given locale dictates your preset default search engine, along with preset quick search options. There are several steps for a "provider" (search engine partner) to become, and remain, compliant. Compliance, and what Mozilla can do with compliant engines, can be better understood by asking the Product team.
A compliant search engine won't always be given as an option for a locale on Firefox-iOS. If an engine is requested enough, then it's worth the effort in providing it as an option for users in their respective locales.
After that's determined, it can be handed off to engineers.
If you're only interested in the process of adding/removing compliant search engines, skip down to the Engineering Handoff section.
On a fresh install, there's preset search engines for the locale you're in. For returning users, it's possible that one may have changed these presets via Settings. In both cases, these are relevant for you as of Jan 2022:
- OpenSearch
- DefaultSearchPrefs
- SearchEngines
- List.json
- All XML files under the SearchPlugins directory.
A user can be a en-US english speaker located in the United States. A user can also be a Welsh speaker located in Singapore. Our system for identifying the "correct" preset search engines will adapt to these, and countless other combinations.
List.json is responsible for this. First, note that locales are Pontoon coded, and NOT Xcode coded.
Every locale has preset search engines. Some locales may have region overrides, and some may have a hard set searchDefault (zh-CN).
Depending on your locale, the preset options for default and quick search varies. The ordering matters. If it's not specified, consider the first search engine the default.
Each search engine is responsible for describing itself. These descriptions follow a standard proposed by a9. If you want to learn more about that, see this github URL and MDN's documents about it. The XMLs that exist in our repo all adhere to this standard. However, engine codes will not be part of the XML.
Engine codes are generated and assigned to each search engine, and hardly ever change. They're extremely important. Making sure we don't mix engine codes between Australia and Canada, for example, is critical.
If you had to support a new search engine, you can expect a XML to be provided to you.
Android does it similarly to us, but Desktop has a different approach. The important things to note from desktop are the search_form and search_url fields. These URLs should match with what you see in the XMLs.
To add, remove or reorder search engines, the developer would likely be interacting only with the engine XMLs and list.json. If you had to add engines, you'll likely need to add the XML to our repo, and edit list.json to add that engine code for the associated locale, in the order product expects. To remove engines, you'll do the opposite.
These are some historical (and one recent) PRs related to this topic: