nontechnical-overview.rst (24682B)
1 Nontechnical Overview 2 ===================== 3 4 This document provides a high level, nontechnical overview of Firefox's address 5 bar, with a focus on the different types of results it shows and how it chooses 6 them. 7 8 .. contents:: 9 :depth: 2 10 11 12 Terminology 13 ----------- 14 15 This document uses a small number of terms of art that would be helpful to 16 understand up front. 17 18 Input 19 The text box component of the address bar. In contrast, we use "address bar" 20 to refer to the whole system comprising the input, the view, and the logic 21 that determines the results that are shown in the view based on the text in 22 the input. 23 24 Result 25 An individual item that is shown in the view. There are many different types 26 of results, including bookmarks, history, open tabs, and search suggestions. 27 28 View 29 The panel that opens below the input when the input is focused. It contains 30 the results. 31 32 Maximum Result Count 33 -------------------- 34 35 The view shows a maximum of 10 results by default. This number is controlled by 36 a hidden preference, ``browser.urlbar.maxRichResults``. 37 38 Search Strings 39 -------------- 40 41 If the user has not modified the text in the input or the text in the input is 42 empty, we say that the user's **search string** is empty, or in other words, 43 there is no search string. In contrast, when the user has modified the text in 44 the input and the text is non-empty, then the search string is that non-empty 45 text. 46 47 .. figure:: assets/nontechnical-overview/empty-url.png 48 :alt: Image of the address bar input showing a URL 49 :scale: 50% 50 :align: center 51 52 Empty search string: The input text has not been modified 53 54 .. figure:: assets/nontechnical-overview/empty-placeholder.png 55 :alt: Image of the address bar input showing its placeholder text 56 :scale: 50% 57 :align: center 58 59 Empty search string: The input text is empty (and the input is showing its 60 placeholder text) 61 62 .. figure:: assets/nontechnical-overview/non-empty.png 63 :alt: Image of the address bar input showing "porcupines" text 64 :scale: 50% 65 :align: center 66 67 Non-empty search string: The input text has been modified and is non-empty 68 69 The distinction between empty and non-empty search strings is helpful to 70 understand for the following sections. 71 72 Top Sites 73 --------- 74 75 When the search string is empty and the user focuses the input, the view opens 76 and shows the user's top sites. They are the same top sites that appear on the 77 new-tab page except their number is capped to the maximum number of address bar 78 results (10). If the user has fewer top sites than the maximum number of results 79 (as is the case in a new profile), then only that number of results is shown. 80 81 .. figure:: assets/nontechnical-overview/top-sites.png 82 :alt: Image of the address bar view showing top sites 83 :scale: 50% 84 :align: center 85 86 Top sites on a new en-US profile 87 88 This behavior can be turned off by going to about:preferences#privacy and 89 unchecking “Shortcuts” in the “Address Bar” section. In that case, the view 90 closes when the search string is empty. 91 92 Searches 93 -------- 94 95 When the search string is non-empty, the address bar performs a search and 96 displays the matching results in the view. Multiple separate searches of 97 different sources are actually performed, and the results from each source are 98 combined, sorted, and capped to the maximum result count to display the final 99 list of results. In address bar terminology, each source is called a 100 **provider**. 101 102 Each provider produces one or more types of results based on the search 103 string. The most common result types include the following (not exhaustive): 104 105 .. figure:: assets/nontechnical-overview/search-suggestion.png 106 :alt: Image of a search suggestion result with text "porcupine meatballs" 107 :scale: 50% 108 :align: center 109 110 Search suggestions from the user's default engine (magnifying glass icon) 111 112 .. figure:: assets/nontechnical-overview/form-history.png 113 :alt: Image of a previous search result with text "porcupines" 114 :scale: 50% 115 :align: center 116 117 Previous searches the user has performed from the address bar and search bar 118 (clock icon) 119 120 .. figure:: assets/nontechnical-overview/bookmark.png 121 :alt: Image of a bookmark result with text "Porcupine - Wikipedia" 122 :scale: 50% 123 :align: center 124 125 Bookmarks 126 127 .. figure:: assets/nontechnical-overview/history.png 128 :alt: Image of a history result with text "Porcupines | National Geographic" 129 :scale: 50% 130 :align: center 131 132 History 133 134 .. figure:: assets/nontechnical-overview/open-tab.png 135 :alt: Image of an open tab result with text "Porcupines | San Diego Zoo 136 Animals & Plants" 137 :scale: 50% 138 :align: center 139 140 Open tabs (switch to tab) 141 142 .. figure:: assets/nontechnical-overview/remote-tab.png 143 :alt: Image of a remote tab result with text "Porcupine | rodent | 144 Britannica" 145 :scale: 50% 146 :align: center 147 148 Remote tabs (via Sync) 149 150 How the address bar combines and sorts results from different providers is 151 discussed below in `Result Composition`_. 152 153 The Heuristic Result 154 -------------------- 155 156 The first result in the view is special and is called the **heuristic** 157 result. As the user types each character in their search string, the heuristic 158 result is updated and automatically selected, and its purpose is to show the 159 user what will happen when they press the enter key without first selecting a 160 (non-heuristic) result. The heuristic result is so called because it shows 161 Firefox's best guess for what the user is trying to do based on their search 162 string. 163 164 The heuristic result is determined by running through a number of different 165 heuristics and picking the one that first matches the search string. The most 166 important heuristics in the order that Firefox runs through them are: 167 168 *Is the search string...* 169 170 1. An omnibox extension keyword? Extensions using the omnibox API can register 171 keywords by which they become activated. 172 2. A bookmark keyword? The user can associate a keyword with each bookmark. 173 Typing a bookmark keyword plus an optional search string and pressing enter 174 will visit the bookmark. 175 176 .. figure:: assets/nontechnical-overview/bookmark-keyword.png 177 :alt: Image of the address bar input with text "bug 1677126" and a 178 bookmark keyword heuristic result 179 :scale: 50% 180 :align: center 181 182 Typing "bug" triggers a Bugzilla bookmark with the keyword "bug" 183 184 3. A domain name or URL that should be autofilled? **Autofill** is the name of 185 the feature where the input completes the domain names and URLs of bookmarks 186 and frequently visited sites as the user is typing them. (Firefox autofills 187 “to the next slash”, meaning it first autofills domain names and then partial 188 paths.) 189 190 .. figure:: assets/nontechnical-overview/autofill.png 191 :alt: Image of the address bar input with text "mozilla.org/" with 192 "illa.org/" selected and an autofill heuristic result 193 :scale: 50% 194 :align: center 195 196 After typing "moz", the rest of mozilla.org is automatically completed 197 198 4. A valid URL? If so, visit the URL. (This includes fixing common typos like 199 “mozilla..org” and “mozilla.ogr”. Valid URLs are based on the `Public Suffix 200 List`_. The user can also specify an allow-list using hidden preferences to 201 support domains like localhost.) 202 203 .. figure:: assets/nontechnical-overview/visit.png 204 :alt: Image of the address bar input with text "porcupine-fancy.org" and a 205 visit heuristic result 206 :scale: 50% 207 :align: center 208 209 Typing a URL that isn't bookmarked or in history 210 211 .. _Public Suffix List: https://publicsuffix.org/ 212 213 5. Ultimately fall back to performing a search using the default engine. (The 214 user can opt out of this fallback by setting the hidden preference 215 ``keyword.enabled`` to false. In that case, Firefox stops at the previous 216 step and attempts to visit the user's search string as if it were a URL.) 217 218 .. figure:: assets/nontechnical-overview/search-heuristic.png 219 :alt: Image of the address bar input with text "porcupines" and a search 220 heuristic result 221 :scale: 50% 222 :align: center 223 224 Typing a string that will perform a search using the default engine 225 226 Result Composition 227 ------------------ 228 229 For a given search string, the address bar performs multiple separate searches 230 of different providers and then combines their results to display the final 231 list. The way in which results are combined and sorted is called **result 232 composition**. Result composition is based on the concept of result groups, one 233 group after another, with different types of results in each group. 234 235 The default result composition is described next, starting with the first 236 result. 237 238 1. Heuristic Result 239 ~~~~~~~~~~~~~~~~~~~ 240 241 The first result is always the heuristic result. 242 243 2. Extension Omnibox Results 244 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 245 246 The next group of results is those provided by extensions using the omnibox 247 API. Most users never encounter these results because they are provided only by 248 extensions that use this feature, and even then the user must type certain 249 extension-defined keywords to trigger them. There are at most 6 results in this 250 group. 251 252 3. Search Suggestions 253 ~~~~~~~~~~~~~~~~~~~~~ 254 255 The next group is search suggestions. Typically this group contains 6 results, 256 but the exact number depends on certain factors described later in `Result 257 Composition Nuances`_. There are actually three types of search suggestions: 258 259 * Previous searches the user has performed from the address bar and search bar 260 (denoted with a clock icon): 261 262 .. image:: assets/nontechnical-overview/form-history.png 263 :alt: Image of a previous search result with text "porcupines" 264 :scale: 50% 265 :align: center 266 267 This is the only type of search suggestion that is generated by Firefox alone, 268 without the help of a search engine. When the user performs a search using an 269 engine from the address bar or search bar (and only the address bar and search 270 bar), Firefox stores the search string, and then when the user starts to type 271 it again, Firefox includes it as a result to make it easy to perform past 272 searches. (Firefox does not store search strings used within web pages like 273 google.com.) 274 275 * Suggestions from the user's default engine (denoted with a magnifying glass 276 icon): 277 278 .. image:: assets/nontechnical-overview/search-suggestion.png 279 :alt: Image of a search suggestion result with text "porcupine meatballs" 280 :scale: 50% 281 :align: center 282 283 These are fetched from the engine if the engine provides the necessary access 284 point. The ordering and total number of these suggestions is determined by the 285 engine. 286 287 * Google-specific "tail" suggestions, which look like "... foo" and are provided 288 for long and/or specific queries to help the user narrow their search: 289 290 .. image:: assets/nontechnical-overview/tail-suggestions.png 291 :alt: Image of a tail suggestion results with text "porcupine abc def" in 292 the input and two suggestions with text "... definition " and 293 "... defense" 294 :scale: 50% 295 :align: center 296 297 These are fetched from Google when Google is the user's default engine. The 298 ordering and total number of these suggestions is determined by Google. 299 300 The search suggestions group typically contains two previous searches followed 301 by four engine suggestions, but the exact numbers depend on the number of 302 matching previous searches and engine suggestions. Previous searches are limited 303 in number so that they don’t dominate this group, allowing remote suggestions to 304 provide content discovery benefits. Tail suggestions are shown only when there 305 are no other suggestions. 306 307 The user can opt out of showing search suggestions in the address bar by 308 visiting about:preferences#search and unchecking "Provide search suggestions" or 309 "Show search suggestions in address bar results". 310 311 4. General Results 312 ~~~~~~~~~~~~~~~~~~ 313 314 The final group of results is a general group that includes the following types: 315 316 * Bookmarks 317 * History 318 * Open tabs (switch to tab) 319 * Remote tabs (via Sync) 320 * Sponsored and Firefox Suggest results (part of the Firefox Suggest feature) 321 322 This general group is labeled "Firefox Suggest" in the Firefox Suggest feature. 323 324 Typically this group contains 3 results, but as with search suggestions, the 325 exact number depends on certain factors (see `Result Composition Nuances`_). 326 327 Most results within this group are first matched against the search string on 328 their titles and URLs and then sorted by a metric called **frecency**, a 329 combination of how frequently and how recently a page is visited. The top three 330 results are shown regardless of their specific types. 331 332 This is the only group that is sorted by frecency. 333 334 A few important complexities of this group are discussed in the next 335 subsections. The final subsection describes frecency in more detail. 336 337 Adaptive History 338 ................ 339 340 The first few bookmark and history results in the general group may come from 341 **adaptive history**, a system that associates specific user search strings with 342 URLs. (It's also known as **input history**.) When the user types a search 343 string and picks a result, Firefox stores a database record that associates the 344 string with the result's URL. When the user types the string or a part of it 345 again, Firefox will try to show the URL they picked last time. This allows 346 Firefox to adapt to a user's habit of visiting certain pages via specific search 347 strings. 348 349 This mechanism is mostly independent of frecency. URLs in the adaptive history 350 database have their own sorting score based on how many times they have been 351 used in the past. The score decays daily so that infrequently used search 352 strings and URLs aren't retained forever. (If two adaptive history results have 353 the same score, they are secondarily sorted by frecency.) 354 355 Within the general group, the number of adaptive history results is not limited, 356 but typically there aren't many of them for a given search string. 357 358 Open and Remote Tabs 359 .................... 360 361 Unlike bookmarks and history, open and remote tabs don't have a "natural" 362 frecency, meaning a frecency that's updated in response to user actions as 363 described below in Frecency_. Tabs that match the search string are assigned 364 constant frecencies so they can participate in the sorting within the general 365 group. Open tabs are assigned a frecency of 1000, and remote tabs are assigned a 366 frecency of 1001. Picking appropriate frecencies is a bit of an art, but Firefox 367 has used these values for some time. 368 369 Sponsored and Firefox Suggest Results 370 ..................................... 371 372 Sponsored and Firefox Suggest results are an exception within this group. They 373 are matched on predetermined keywords, and when present, they always appear last 374 in the general group. Frecency isn't involved at all. 375 376 Frecency 377 ........ 378 379 Frecency is a complex topic on its own, but in summary, each URL stored in 380 Firefox's internal history database has a numeric score, the frecency, 381 associated with it. Larger numbers mean higher frecencies, and URLs with higher 382 frecencies are more likely to be surfaced to the user via the address bar. Each 383 time the user visits a URL, Firefox increases its frecency by a certain "boost" 384 amount that depends on how the visit is performed -- whether the user picked it 385 in the address bar, clicked its link on a page, clicked it in the history 386 sidebar, etc. In order to prevent frecencies from growing unbounded and to 387 penalize URLs that haven't been visited in a while, Firefox decays the 388 frecencies of all URLs over time. 389 390 For details on frecency, see `The Frecency Algorithm`_. 391 392 .. _The Frecency Algorithm: https://docs.google.com/document/d/10LRRXVGWWWcjEZIZ2YlEmuKkQqh2RaTclStFHNnPqQ8/edit#heading=h.588hanspexub 393 394 Preferences that Affect Result Composition 395 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 396 397 There are a number of options in about:preferences that affect result 398 composition. 399 400 The user can opt out of showing search suggestions in the address bar by 401 unchecking "Provide search suggestions" or "Show search suggestions in address 402 bar results" in about:preferences#search. (The first checkbox applies to both 403 the address bar and search bar, so it acts as a global toggle.) 404 405 .. figure:: assets/nontechnical-overview/prefs-show-suggestions.png 406 :alt: Image of the preferences UI that allows the user to opt out of search 407 suggestions 408 :scale: 50% 409 :align: center 410 411 Preferences allowing the user to opt out of search suggestions 412 413 By default, the search suggestions group is shown before the general results 414 group, but unchecking "Show search suggestions ahead of browsing history in 415 address bar results" in about:preferences#search does the opposite. In that 416 case, typically the general results group will contain at most 6 results and the 417 search suggestions group will contain at most 3. In other words, regardless of 418 which group comes first, typically the first will contain 6 results and the 419 second will contain 3. 420 421 .. figure:: assets/nontechnical-overview/prefs-suggestions-first.png 422 :alt: Image of the preferences UI that allows the user to choose whether 423 search suggestions are shown before general results 424 :scale: 50% 425 :align: center 426 427 Preference allowing the user to choose which group is shown first 428 429 The “Address Bar” section in about:preferences#privacy has several checkboxes 430 that allow for finer control over the types of results that appear in the view. 431 The top sites feature can be turned off by unchecking “Shortcuts” in this 432 section. 433 434 .. figure:: assets/nontechnical-overview/prefs-privacy.png 435 :alt: Image of the preferences UI that allows the user to choose which 436 results are shown 437 :scale: 50% 438 :align: center 439 440 Preferences allowing the user to choose which results are shown 441 442 Result Composition Nuances 443 -------------------------- 444 445 Among the search suggestions and general results groups, the group that's shown 446 first typically contains 6 results and the other group contains 3 results. The 447 exact number in each group depends on several factors: 448 449 * The total maximum result count (controlled by the 450 ``browser.urlbar.maxRichResults`` hidden preference). 451 452 The total number of results in the two groups scales up and down to 453 accommodate this number so that the view is always full of results. 454 455 * The number of extension results. 456 457 The extension results group comes before both groups, so if there are any 458 extension results, there are fewer available slots for search suggestions and 459 general results. 460 461 * The number of matching results. 462 463 The search string may match only one or two search suggestions or general 464 results, for example. 465 466 * The number of results in the other group. 467 468 The first group will try to contain 6 results and the second will try to 469 contain 3, but if either one is unable to fill up, then the other group will 470 be allowed to grow to make up the difference. 471 472 Other Result Types 473 ------------------ 474 475 The most common result types are discussed above. This section walks through the 476 other types. 477 478 An important trait these types have in common is that they do not belong to any 479 group. Most of them appear at specific positions within the view. 480 481 Search Interventions 482 ~~~~~~~~~~~~~~~~~~~~ 483 484 Search interventions help the user perform a task based on their search string. 485 There are three kinds of interventions, and each is triggered by typing a 486 certain set of phrases_ in the input. They always appear as the second result, 487 after the heuristic result. 488 489 The three kinds of interventions are: 490 491 .. figure:: assets/nontechnical-overview/intervention-clear.png 492 :alt: Image of the clear intervention result with text "Clear your cache, 493 cookies, history and more" 494 :scale: 50% 495 :align: center 496 497 Clear history, cache, and other data search intervention 498 499 .. figure:: assets/nontechnical-overview/intervention-refresh.png 500 :alt: Image of the refresh intervention result with text "Restore default 501 settings and remove old add-ons for optimal performance" 502 :scale: 50% 503 :align: center 504 505 Refresh Firefox search intervention 506 507 .. figure:: assets/nontechnical-overview/intervention-update.png 508 :alt: Image of the update intervention result with text "The latest Firefox 509 is downloaded and ready to install" 510 :scale: 50% 511 :align: center 512 513 Update Firefox search intervention 514 515 Currently this feature is limited to English-speaking locales, but work is 516 ongoing to build a more sophisticated intent-matching platform to support other 517 locales, more complex search strings, and more kinds of interventions. 518 519 .. _phrases: https://searchfox.org/mozilla-central/rev/c4d682be93f090e99d5f4049ceb7b6b6c03d0632/browser/components/urlbar/UrlbarProviderInterventions.jsm#64 520 521 Search Tips 522 ~~~~~~~~~~~ 523 524 Search tips inform the user they can perform searches directly from the 525 address bar. There are two kinds of search tips: 526 527 .. figure:: assets/nontechnical-overview/search-tip-onboard.png 528 :alt: Image of the onboarding search tip with text "Type less, find more: 529 Search Google right from your address bar" 530 :scale: 50% 531 :align: center 532 533 Onboarding search tip: Appears on the new-tab page 534 535 .. figure:: assets/nontechnical-overview/search-tip-redirect.png 536 :alt: Image of the redirect search tip with text "Start your search in the 537 address bar to see suggestions from Google and your browsing history" 538 :scale: 50% 539 :align: center 540 541 Redirect search tip: Appears on the home page of the user's default engine 542 (only for Google, Bing, and DuckDuckGo) 543 544 In each case, the view automatically opens and shows the tip even if the user is 545 not interacting with the address bar. Each tip is shown at most four times, and 546 the user can stop them from appearing altogether by interacting with the address 547 bar or clicking the "Okay, Got It" button. 548 549 Tab to Search 550 ~~~~~~~~~~~~~ 551 552 Tab to search allows the user to press the tab key to enter `search mode`_ while 553 typing the domain name of a search engine. There are two kinds of tab-to-search 554 results, and they always appear as the second result: 555 556 .. figure:: assets/nontechnical-overview/tab-to-search-onboard.png 557 :alt: Image of the tab-to-search result with text "Search with Google" 558 :scale: 50% 559 :align: center 560 561 Onboarding tab to search 562 563 .. figure:: assets/nontechnical-overview/tab-to-search-regular.png 564 :alt: Image of the tab-to-search result with text "Search with Google" 565 :scale: 50% 566 :align: center 567 568 Regular tab to search 569 570 The onboarding type is shown until the user has interacted with it three times 571 over a period of at least 15 minutes, and after that the regular type is shown. 572 573 Search Engine Offers 574 ~~~~~~~~~~~~~~~~~~~~ 575 576 Typing a single “@” shows a list of search engines. Selecting an engine enters 577 `search mode`_. 578 579 .. figure:: assets/nontechnical-overview/search-offers.png 580 :alt: Image of the view showing search offer results 581 :scale: 50% 582 :align: center 583 584 Search engine offers after typing “@” 585 586 .. figure:: assets/nontechnical-overview/search-offers-selected.png 587 :alt: Image of the view showing search offer results with one selected 588 :scale: 50% 589 :align: center 590 591 After pressing the down arrow key to select Google 592 593 Search Mode 594 ----------- 595 596 **Search mode** is a feature that transforms the address bar into a search-only 597 access point for a particular engine. During search mode, search suggestions are 598 the only results shown in the view, and for that reason its result composition 599 differs from the usual composition. 600 601 .. figure:: assets/nontechnical-overview/search-mode.png 602 :alt: Image of the view showing search mode 603 :scale: 50% 604 :align: center 605 606 Search mode with Google as the selected engine 607 608 Firefox shows suggestions in search mode even when the user has otherwise opted 609 out of them. Our rationale is that by entering search mode, the user has taken 610 an action that overrides their usual opt out. This allows the user to opt out 611 generally but opt back in at specific times. 612 613 Search mode is an effective replacement for the legacy search bar and may 614 provide a good path forward for deprecating it. 615 616 The user can enter search mode in many ways: 617 618 * Picking a search shortcut button at the bottom of the view 619 * Typing an engine's keyword (which can be set in about:preferences#search, and 620 built-in engines have default keywords) 621 * Typing a single "?" followed by a space (to enter search mode with the default 622 engine) 623 * Typing a single "@" to list all engines and then picking one 624 * If the search bar is not also shown, pressing Ctrl+K (to enter search mode 625 with the default engine) 626 627 To exit search mode, the user can backspace over the engine chiclet or click its 628 close button.