Adaptive History Autofill in Firefox

This document provides an overview of autofill in Firefox’s address bar with a focus on adaptive history autofill.

This document is published to the web so that anyone can view it.
The published version is linked from the address bar’s telemetry documentation.
It should be moved to Firefox’s in-tree documentation at some point.
The Mozilla-internal version is here and was adapted from a QA doc.

Overview

When the user types a search string in the address bar and picks a result, Firefox stores a database record that associates the search string with the result’s URL. When the user types the search string again – or part of the search string – the address bar will show the result they picked last time. This feature is called adaptive history.

Here are some examples of adaptive history database records:

Example adaptive history records. Each record has a search string and URL. There are other fields in each record as well, discussed later.

Adaptive history autofill is a new feature where the address bar will autofill full URLs based on adaptive history. The address bar will use one feature, adaptive history, to improve another feature, autofill. When the user starts typing a search string that is stored in adaptive history, the associated full URL will be autofilled.

Adaptive history autofill as the user is typing “mozilla”. In this example, there is an adaptive history record with search string “moz” and the URL “mozilla.org/en-US/firefox/”. When the user types “m” and “mo”, origin autofill is used (see below). Once the user types “moz” and continues typing the rest of “mozilla”, adaptive history autofill is used and the full URL is autofilled.

Firefox has two other kinds of autofill: origin autofill and URL autofill. Origin autofill works by autofilling domain names, for example “mozilla.org”, “google.com”, “youtube.com”, etc. As the user begins typing their search string, origin autofill is triggered before URL autofill. In order for a domain name to be autofilled, it must have a frecency value over a certain threshold.

Origin autofill as the user is typing “mozilla”. Only the domain name “mozilla.org” is autofilled.

After the user types a slash (“/”), URL autofill is triggered. URL autofill works by autofilling URLs “up to the next slash.” For example, after the user types “mozilla.org/e”, Firefox may autofill “mozilla.org/en-US/”. If the user then types “f”, Firefox may autofill “mozilla.org/en-US/firefox/”. Only URLs in the user’s history will be autofilled.

URL autofill. The URL “mozilla.org/en-US/firefox/” is autofilled up to the next slash as the user types “en-US” and “firefox”.

Origin and URL autofill still exist, but adaptive history autofill will now take precedence. When a record exists in adaptive history that starts with the user’s search string, adaptive history autofill will be used; otherwise Firefox will fall back to origin or URL autofill.

How to add adaptive history

In order to trigger adaptive history autofill, first you’ll need to add some adaptive history. An adaptive history database record is created or updated when all of the following are true:

The user picks a result.
Either the result is not the heuristic result, or it is an adaptive history autofill heuristic result. (The heuristic result is the first, pre-selected result that’s shown when the user types something.)

In other words, the record isn’t updated when the user picks the heuristic result unless it’s the adaptive history autofill result.

Picking the result causes a URL to load.
The URL is already present in the user’s history or bookmarks. (This seems to be unintentional and caused by a race condition between adding the URL to adaptive history and adding it to browsing history. You may find that sometimes adaptive history will successfully be added for new URLs.)
The window is not private.

Use counts

Each adaptive history record has a use count that is proportional to the number of times the record was updated. In other words, it’s proportional to the number of times the user typed the record’s search string and picked its URL. Records with larger use counts have been used more often (and more recently) than records with smaller use counts.

The use count is not a simple integer that’s incremented each time the record is updated. Instead it is incremented with a value proportional to itself such that the use count will never be greater than 10. It’s not important to understand the math.

The use counts of all records are decreased (“decayed”) periodically. This prevents records that have not been updated recently from keeping a high use count.

How to remove adaptive history

To remove an adaptive history record, remove its URL from browsing history and bookmarks. URLs can be removed from browsing history in any of the following usual ways:

Clear Recent History
Forget About This Site
Delete individual entries from the history sidebar or Library
Select a result in the address bar panel using the keyboard and press Shift+Delete

There’s no way to remove adaptive history without removing browsing history. That means there’s no way to prevent adaptive history autofill from being triggered for a certain search string and URL other than removing the URL from browsing history (or disabling autofill).

How to trigger adaptive history autofill without the experiment

To trigger an adaptive history record for autofill without the experiment, all of the following must be true:

Adaptive history autofill must be enabled. Set browser.urlbar.autoFill.adaptiveHistory.enabled to true.
The search string the user is typing must start with the record’s search string.

Example: The user has typed “mozilla” and the record’s search string is “moz”
Example: The user has typed “moz” and the record’s search string is “moz”

The record’s URL must also start with the search string the user is typing, with one exception: If the URL starts with “www”, Firefox will also try to match the part of the URL after the “www”. (This rule also applies to origin autofill.)

Example: If a record’s search string is “mozilla” and its URL is “www.mozilla.org/firefox”, the record will be matched when the user types “mozilla” even though the URL starts with “www”.

The record’s use count must be greater than or equal to a certain threshold use count, which is 0.47 by default and is defined by the hidden preference named browser.urlbar.autoFill.adaptiveHistory.useCountThreshold.
The search string the user is typing must be at least as long as the value defined by the hidden preference named browser.urlbar.autoFill.adaptiveHistory.minCharsThreshold. The default value of this preference is 0, so by default there is no threshold and this will always be true.
There is not some other higher priority adaptive history record that will be autofilled for the search string instead. See the Priority section below.

How to trigger adaptive history autofill with the experiment

Triggering adaptive history autofill while enrolled in the treatment branch of the experiment is similar to the previous section but not exactly the same. There is one additional condition that must be true:

The user’s search string must be at least 4 characters long.

This means if an adaptive history record’s search string is less than 4 characters long, its URL cannot be autofilled until the user types at least 4 characters. For example, if a record’s search string is “moz” and the user types “moz”, the record’s URL will not be autofilled. If the user then types one more character, e.g. “mozi”, the URL will be autofilled as long as its URL starts with “mozi”.

The purpose of this extra condition is to make it less likely that adaptive history autofill will annoy the user.

Priority logic

The search string the user is typing may match multiple records in adaptive history. Firefox will pick the one using the following priority logic:

In descending order of use count. In other words, largest use count wins.
If the above is the same, the record whose search string does not start with “www” or a protocol like “http://” and “https://”.
If the above is the same, in descending order of frecency.
If the above is the same, newer records before older records.

If no adaptive history record matches, then Firefox will fall back to origin and URL autofill. Of course it’s possible that the user’s search string won’t trigger any kind of autofill.

Important points

An adaptive history record’s search string may not “match” its URL. The URL does not need to start with the record’s search string or even contain it. That can be the case when the user typed a search string that was present in the page’s title but not its URL, for example. In the following adaptive history record, the URL does not contain the “adap” search string at all:
The same search string may be present in multiple adaptive history records.
Autofill is case-insensitive. If there is an adaptive history record whose search string is “EXA”, it will be autofilled by “eXa” as well. In that case, “eXa” should be used in the final URL that is loaded when the user presses the Enter key. In other words, the search string that the user is currently typing should be used in the final URL.
HTTP redirects are not directly relevant to this feature. As long as a URL is present in adaptive history, it can participate in adaptive history autofill.
The ability to stop specific adaptive history records from autofilling is not part of the spec for this feature.
An adaptive history record will stop autofilling when any one of the following happens:

The URL is removed from history and the URL is not also bookmarked. (If the URL remains bookmarked, the record can still be autofilled.)
The use count decays below the autofill threshold.
Another similar adaptive history record gains a higher priority. (See the Priority section.) In that case, the other record will be autofilled instead.

Preferences

browser.urlbar.autoFill

This is the global toggle for all autofill. When it’s false, all autofill should be disabled (including all three types: adaptive history, origin, and URL).

browser.urlbar.autoFill.adaptiveHistory.enabled

Enables or disables the adaptive history autofill feature. It’s currently disabled by default. This pref is not related to origin or URL autofill, so when it’s false, origin and URL autofill should remain enabled (unless all autofill has been disabled using browser.urlbar.autoFill).

browser.urlbar.autoFill.adaptiveHistory.minCharsThreshold

In order to trigger any adaptive history autofill, the search string the user is typing must be at least this many characters. Its default value without the experiment is 0, which means there is no threshold. In the treatment branch of the experiment, the threshold is set to 4 (but note that the threshold in that case is set using a Nimbus variable, not the pref, so the pref value will remain 0).

browser.urlbar.autoFill.adaptiveHistory.useCountThreshold

In order for an adaptive history record to be autofilled, its use count must be at least this threshold value. Its default value is 0.47.