diff options
Diffstat (limited to 'browser/components/urlbar/UrlbarController.sys.mjs')
| -rw-r--r-- | browser/components/urlbar/UrlbarController.sys.mjs | 1399 |
1 files changed, 1399 insertions, 0 deletions
diff --git a/browser/components/urlbar/UrlbarController.sys.mjs b/browser/components/urlbar/UrlbarController.sys.mjs new file mode 100644 index 0000000000..563a6b7963 --- /dev/null +++ b/browser/components/urlbar/UrlbarController.sys.mjs @@ -0,0 +1,1399 @@ +/* This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ + +import { XPCOMUtils } from "resource://gre/modules/XPCOMUtils.sys.mjs"; + +import { AppConstants } from "resource://gre/modules/AppConstants.sys.mjs"; + +const lazy = {}; + +ChromeUtils.defineESModuleGetters(lazy, { + BrowserSearchTelemetry: "resource:///modules/BrowserSearchTelemetry.sys.mjs", + UrlbarPrefs: "resource:///modules/UrlbarPrefs.sys.mjs", + UrlbarProvidersManager: "resource:///modules/UrlbarProvidersManager.sys.mjs", + UrlbarTokenizer: "resource:///modules/UrlbarTokenizer.sys.mjs", + UrlbarUtils: "resource:///modules/UrlbarUtils.sys.mjs", + clearTimeout: "resource://gre/modules/Timer.sys.mjs", + setTimeout: "resource://gre/modules/Timer.sys.mjs", +}); + +const TELEMETRY_1ST_RESULT = "PLACES_AUTOCOMPLETE_1ST_RESULT_TIME_MS"; +const TELEMETRY_6_FIRST_RESULTS = "PLACES_AUTOCOMPLETE_6_FIRST_RESULTS_TIME_MS"; + +const TELEMETRY_SCALAR_ENGAGEMENT = "urlbar.engagement"; +const TELEMETRY_SCALAR_ABANDONMENT = "urlbar.abandonment"; + +const NOTIFICATIONS = { + QUERY_STARTED: "onQueryStarted", + QUERY_RESULTS: "onQueryResults", + QUERY_RESULT_REMOVED: "onQueryResultRemoved", + QUERY_CANCELLED: "onQueryCancelled", + QUERY_FINISHED: "onQueryFinished", + VIEW_OPEN: "onViewOpen", + VIEW_CLOSE: "onViewClose", +}; + +/** + * The address bar controller handles queries from the address bar, obtains + * results and returns them to the UI for display. + * + * Listeners may be added to listen for the results. They may support the + * following methods which may be called when a query is run: + * + * - onQueryStarted(queryContext) + * - onQueryResults(queryContext) + * - onQueryCancelled(queryContext) + * - onQueryFinished(queryContext) + * - onQueryResultRemoved(index) + * - onViewOpen() + * - onViewClose() + */ +export class UrlbarController { + /** + * Initialises the class. The manager may be overridden here, this is for + * test purposes. + * + * @param {object} options + * The initial options for UrlbarController. + * @param {UrlbarInput} options.input + * The input this controller is operating with. + * @param {object} [options.manager] + * Optional fake providers manager to override the built-in providers manager. + * Intended for use in unit tests only. + */ + constructor(options = {}) { + if (!options.input) { + throw new Error("Missing options: input"); + } + if (!options.input.window) { + throw new Error("input is missing 'window' property."); + } + if ( + !options.input.window.location || + options.input.window.location.href != AppConstants.BROWSER_CHROME_URL + ) { + throw new Error("input.window should be an actual browser window."); + } + if (!("isPrivate" in options.input)) { + throw new Error("input.isPrivate must be set."); + } + + this.input = options.input; + this.browserWindow = options.input.window; + + this.manager = options.manager || lazy.UrlbarProvidersManager; + + this._listeners = new Set(); + this._userSelectionBehavior = "none"; + + this.engagementEvent = new TelemetryEvent( + this, + options.eventTelemetryCategory + ); + + XPCOMUtils.defineLazyGetter(this, "logger", () => + lazy.UrlbarUtils.getLogger({ prefix: "Controller" }) + ); + } + + get NOTIFICATIONS() { + return NOTIFICATIONS; + } + + /** + * Hooks up the controller with a view. + * + * @param {UrlbarView} view + * The UrlbarView instance associated with this controller. + */ + setView(view) { + this.view = view; + } + + /** + * Takes a query context and starts the query based on the user input. + * + * @param {UrlbarQueryContext} queryContext The query details. + */ + async startQuery(queryContext) { + // Cancel any running query. + this.cancelQuery(); + + // Wrap the external queryContext, to track a unique object, in case + // the external consumer reuses the same context multiple times. + // This also allows to add properties without polluting the context. + // Note this can't be null-ed or deleted once a query is done, because it's + // used by #dismissSelectedResult and handleKeyNavigation, that can run after + // a query is cancelled or finished. + let contextWrapper = (this._lastQueryContextWrapper = { queryContext }); + + queryContext.lastResultCount = 0; + TelemetryStopwatch.start(TELEMETRY_1ST_RESULT, queryContext); + TelemetryStopwatch.start(TELEMETRY_6_FIRST_RESULTS, queryContext); + + // For proper functionality we must ensure this notification is fired + // synchronously, as soon as startQuery is invoked, but after any + // notifications related to the previous query. + this.notify(NOTIFICATIONS.QUERY_STARTED, queryContext); + await this.manager.startQuery(queryContext, this); + // If the query has been cancelled, onQueryFinished was notified already. + // Note this._lastQueryContextWrapper may have changed in the meanwhile. + if ( + contextWrapper === this._lastQueryContextWrapper && + !contextWrapper.done + ) { + contextWrapper.done = true; + // TODO (Bug 1549936) this is necessary to avoid leaks in PB tests. + this.manager.cancelQuery(queryContext); + this.notify(NOTIFICATIONS.QUERY_FINISHED, queryContext); + } + return queryContext; + } + + /** + * Cancels an in-progress query. Note, queries may continue running if they + * can't be cancelled. + */ + cancelQuery() { + // We must clear the pause impression timer in any case, even if the query + // already finished. + this.engagementEvent.clearPauseImpressionTimer(); + + // If the query finished already, don't handle cancel. + if (!this._lastQueryContextWrapper || this._lastQueryContextWrapper.done) { + return; + } + + this._lastQueryContextWrapper.done = true; + + let { queryContext } = this._lastQueryContextWrapper; + TelemetryStopwatch.cancel(TELEMETRY_1ST_RESULT, queryContext); + TelemetryStopwatch.cancel(TELEMETRY_6_FIRST_RESULTS, queryContext); + this.manager.cancelQuery(queryContext); + this.notify(NOTIFICATIONS.QUERY_CANCELLED, queryContext); + this.notify(NOTIFICATIONS.QUERY_FINISHED, queryContext); + } + + /** + * Receives results from a query. + * + * @param {UrlbarQueryContext} queryContext The query details. + */ + receiveResults(queryContext) { + if (queryContext.lastResultCount < 1 && queryContext.results.length >= 1) { + TelemetryStopwatch.finish(TELEMETRY_1ST_RESULT, queryContext); + } + if (queryContext.lastResultCount < 6 && queryContext.results.length >= 6) { + TelemetryStopwatch.finish(TELEMETRY_6_FIRST_RESULTS, queryContext); + } + + this.engagementEvent.startPauseImpressionTimer( + queryContext, + this.input.getSearchSource() + ); + + if (queryContext.firstResultChanged) { + // Notify the input so it can make adjustments based on the first result. + if (this.input.onFirstResult(queryContext.results[0])) { + // The input canceled the query and started a new one. + return; + } + + // The first time we receive results try to connect to the heuristic + // result. + this.speculativeConnect( + queryContext.results[0], + queryContext, + "resultsadded" + ); + } + + this.notify(NOTIFICATIONS.QUERY_RESULTS, queryContext); + // Update lastResultCount after notifying, so the view can use it. + queryContext.lastResultCount = queryContext.results.length; + } + + /** + * Adds a listener for query actions and results. + * + * @param {object} listener The listener to add. + * @throws {TypeError} Throws if the listener is not an object. + */ + addQueryListener(listener) { + if (!listener || typeof listener != "object") { + throw new TypeError("Expected listener to be an object"); + } + this._listeners.add(listener); + } + + /** + * Removes a query listener. + * + * @param {object} listener The listener to add. + */ + removeQueryListener(listener) { + this._listeners.delete(listener); + } + + /** + * Checks whether a keyboard event that would normally open the view should + * instead be handled natively by the input field. + * On certain platforms, the up and down keys can be used to move the caret, + * in which case we only want to open the view if the caret is at the + * start or end of the input. + * + * @param {KeyboardEvent} event + * The DOM KeyboardEvent. + * @returns {boolean} + * Returns true if the event should move the caret instead of opening the + * view. + */ + keyEventMovesCaret(event) { + if (this.view.isOpen) { + return false; + } + if (AppConstants.platform != "macosx" && AppConstants.platform != "linux") { + return false; + } + let isArrowUp = event.keyCode == KeyEvent.DOM_VK_UP; + let isArrowDown = event.keyCode == KeyEvent.DOM_VK_DOWN; + if (!isArrowUp && !isArrowDown) { + return false; + } + let start = this.input.selectionStart; + let end = this.input.selectionEnd; + if ( + end != start || + (isArrowUp && start > 0) || + (isArrowDown && end < this.input.value.length) + ) { + return true; + } + return false; + } + + /** + * Receives keyboard events from the input and handles those that should + * navigate within the view or pick the currently selected item. + * + * @param {KeyboardEvent} event + * The DOM KeyboardEvent. + * @param {boolean} executeAction + * Whether the event should actually execute the associated action, or just + * be managed (at a preventDefault() level). This is used when the event + * will be deferred by the event bufferer, but preventDefault() and friends + * should still happen synchronously. + */ + handleKeyNavigation(event, executeAction = true) { + const isMac = AppConstants.platform == "macosx"; + // Handle readline/emacs-style navigation bindings on Mac. + if ( + isMac && + this.view.isOpen && + event.ctrlKey && + (event.key == "n" || event.key == "p") + ) { + if (executeAction) { + this.view.selectBy(1, { reverse: event.key == "p" }); + } + event.preventDefault(); + return; + } + + if (this.view.isOpen && executeAction && this._lastQueryContextWrapper) { + let { queryContext } = this._lastQueryContextWrapper; + let handled = this.view.oneOffSearchButtons.handleKeyDown( + event, + this.view.visibleRowCount, + this.view.allowEmptySelection, + queryContext.searchString + ); + if (handled) { + return; + } + } + + switch (event.keyCode) { + case KeyEvent.DOM_VK_ESCAPE: + if (executeAction) { + if (this.view.isOpen) { + this.view.close(); + } else { + this.input.handleRevert(true); + } + } + event.preventDefault(); + break; + case KeyEvent.DOM_VK_SPACE: + if (!this.view.shouldSpaceActivateSelectedElement()) { + break; + } + // Fall through, we want the SPACE key to activate this element. + case KeyEvent.DOM_VK_RETURN: + if (executeAction) { + this.input.handleCommand(event); + } + event.preventDefault(); + break; + case KeyEvent.DOM_VK_TAB: + // It's always possible to tab through results when the urlbar was + // focused with the mouse or has a search string, or when the view + // already has a selection. + // We allow tabbing without a search string when in search mode preview, + // since that means the user has interacted with the Urlbar since + // opening it. + // When there's no search string and no view selection, we want to focus + // the next toolbar item instead, for accessibility reasons. + let allowTabbingThroughResults = + this.input.focusedViaMousedown || + this.input.searchMode?.isPreview || + this.view.selectedElement || + (this.input.value && + this.input.getAttribute("pageproxystate") != "valid"); + if ( + // Even if the view is closed, we may be waiting results, and in + // such a case we don't want to tab out of the urlbar. + (this.view.isOpen || !executeAction) && + !event.ctrlKey && + !event.altKey && + allowTabbingThroughResults + ) { + if (executeAction) { + this.userSelectionBehavior = "tab"; + this.view.selectBy(1, { + reverse: event.shiftKey, + userPressedTab: true, + }); + } + event.preventDefault(); + } + break; + case KeyEvent.DOM_VK_PAGE_DOWN: + case KeyEvent.DOM_VK_PAGE_UP: + if (event.ctrlKey) { + break; + } + // eslint-disable-next-lined no-fallthrough + case KeyEvent.DOM_VK_DOWN: + case KeyEvent.DOM_VK_UP: + if (event.altKey) { + break; + } + if (this.view.isOpen) { + if (executeAction) { + this.userSelectionBehavior = "arrow"; + this.view.selectBy( + event.keyCode == KeyEvent.DOM_VK_PAGE_DOWN || + event.keyCode == KeyEvent.DOM_VK_PAGE_UP + ? lazy.UrlbarUtils.PAGE_UP_DOWN_DELTA + : 1, + { + reverse: + event.keyCode == KeyEvent.DOM_VK_UP || + event.keyCode == KeyEvent.DOM_VK_PAGE_UP, + } + ); + } + } else { + if (this.keyEventMovesCaret(event)) { + break; + } + if (executeAction) { + this.userSelectionBehavior = "arrow"; + this.input.startQuery({ + searchString: this.input.value, + event, + }); + } + } + event.preventDefault(); + break; + case KeyEvent.DOM_VK_RIGHT: + case KeyEvent.DOM_VK_END: + this.input.maybeConfirmSearchModeFromResult({ + entry: "typed", + }); + // Fall through. + case KeyEvent.DOM_VK_LEFT: + case KeyEvent.DOM_VK_HOME: + this.view.removeAccessibleFocus(); + break; + case KeyEvent.DOM_VK_BACK_SPACE: + if ( + this.input.searchMode && + this.input.selectionStart == 0 && + this.input.selectionEnd == 0 && + !event.shiftKey + ) { + this.input.searchMode = null; + this.input.view.oneOffSearchButtons.selectedButton = null; + this.input.startQuery({ + allowAutofill: false, + event, + }); + } + // Fall through. + case KeyEvent.DOM_VK_DELETE: + if (!this.view.isOpen) { + break; + } + if (event.shiftKey) { + if (!executeAction || this.#dismissSelectedResult(event)) { + event.preventDefault(); + } + } else if (executeAction) { + this.userSelectionBehavior = "none"; + } + break; + } + } + + /** + * Tries to initialize a speculative connection on a result. + * Speculative connections are only supported for a subset of all the results. + * + * Speculative connect to: + * - Search engine heuristic results + * - autofill results + * - http/https results + * + * @param {UrlbarResult} result The result to speculative connect to. + * @param {UrlbarQueryContext} context The queryContext + * @param {string} reason Reason for the speculative connect request. + */ + speculativeConnect(result, context, reason) { + // Never speculative connect in private contexts. + if (!this.input || context.isPrivate || !context.results.length) { + return; + } + let { url } = lazy.UrlbarUtils.getUrlFromResult(result); + if (!url) { + return; + } + + switch (reason) { + case "resultsadded": { + // We should connect to an heuristic result, if it exists. + if ( + (result == context.results[0] && result.heuristic) || + result.autofill + ) { + if (result.type == lazy.UrlbarUtils.RESULT_TYPE.SEARCH) { + // Speculative connect only if search suggestions are enabled. + if ( + lazy.UrlbarPrefs.get("suggest.searches") && + lazy.UrlbarPrefs.get("browser.search.suggest.enabled") + ) { + let engine = Services.search.getEngineByName( + result.payload.engine + ); + lazy.UrlbarUtils.setupSpeculativeConnection( + engine, + this.browserWindow + ); + } + } else if (result.autofill) { + lazy.UrlbarUtils.setupSpeculativeConnection( + url, + this.browserWindow + ); + } + } + return; + } + case "mousedown": { + // On mousedown, connect only to http/https urls. + if (url.startsWith("http")) { + lazy.UrlbarUtils.setupSpeculativeConnection(url, this.browserWindow); + } + return; + } + default: { + throw new Error("Invalid speculative connection reason"); + } + } + } + + /** + * Stores the selection behavior that the user has used to select a result. + * + * @param {"arrow"|"tab"|"none"} behavior + * The behavior the user used. + */ + set userSelectionBehavior(behavior) { + // Don't change the behavior to arrow if tab has already been recorded, + // as we want to know that the tab was used first. + if (behavior == "arrow" && this._userSelectionBehavior == "tab") { + return; + } + this._userSelectionBehavior = behavior; + } + + /** + * Records details of the selected result in telemetry. We only record the + * selection behavior, type and index. + * + * @param {Event} event + * The event which triggered the result to be selected. + * @param {UrlbarResult} result + * The selected result. + */ + recordSelectedResult(event, result) { + let resultIndex = result ? result.rowIndex : -1; + let selectedResult = -1; + if (resultIndex >= 0) { + // Except for the history popup, the urlbar always has a selection. The + // first result at index 0 is the "heuristic" result that indicates what + // will happen when you press the Enter key. Treat it as no selection. + selectedResult = resultIndex > 0 || !result.heuristic ? resultIndex : -1; + } + lazy.BrowserSearchTelemetry.recordSearchSuggestionSelectionMethod( + event, + "urlbar", + selectedResult, + this._userSelectionBehavior + ); + + if (!result) { + return; + } + + // Do not modify existing telemetry types. To add a new type: + // + // * Set telemetryType appropriately. Since telemetryType is used as the + // probe name, it must be alphanumeric with optional underscores. + // * Add a new keyed scalar probe into the urlbar.picked category for the + // newly added telemetryType. + // * Add a test named browser_UsageTelemetry_urlbar_newType.js to + // browser/modules/test/browser. + // + // The "topsite" type overrides the other ones, because it starts from a + // unique user interaction, that we want to count apart. We do this here + // rather than in telemetryTypeFromResult because other consumers, like + // events telemetry, are reporting this information separately. + let telemetryType = + result.providerName == "UrlbarProviderTopSites" + ? "topsite" + : lazy.UrlbarUtils.telemetryTypeFromResult(result); + Services.telemetry.keyedScalarAdd( + `urlbar.picked.${telemetryType}`, + resultIndex, + 1 + ); + if (this.input.searchMode && !this.input.searchMode.isPreview) { + Services.telemetry.keyedScalarAdd( + `urlbar.picked.searchmode.${this.input.searchMode.entry}`, + resultIndex, + 1 + ); + } + } + + /** + * Triggers a "dismiss" engagement for the selected result if one is selected + * and it's not the heuristic. Providers that can respond to dismissals of + * their results should implement `onEngagement()`, handle the dismissal, and + * call `controller.removeResult()`. + * + * @param {Event} event + * The event that triggered dismissal. + * @returns {boolean} + * Whether providers were notified about the engagement. Providers will not + * be notified if there is no selected result or the selected result is the + * heuristic, since the heuristic result cannot be dismissed. + */ + #dismissSelectedResult(event) { + if (!this._lastQueryContextWrapper) { + console.error("Cannot dismiss selected result, last query not present"); + return false; + } + let { queryContext } = this._lastQueryContextWrapper; + + let { selectedElement } = this.input.view; + if (selectedElement?.classList.contains("urlbarView-button")) { + // For results with buttons, delete them only when the main part of the + // row is selected, not a button. + return false; + } + + let result = this.input.view.selectedResult; + if (!result || result.heuristic) { + return false; + } + + this.engagementEvent.record(event, { + result, + selType: "dismiss", + searchString: queryContext.searchString, + }); + + return true; + } + + /** + * Removes a result from the current query context and notifies listeners. + * Heuristic results cannot be removed. + * + * @param {UrlbarResult} result + * The result to remove. + */ + removeResult(result) { + if (!result || result.heuristic) { + return; + } + + if (!this._lastQueryContextWrapper) { + console.error("Cannot remove result, last query not present"); + return; + } + let { queryContext } = this._lastQueryContextWrapper; + + let index = queryContext.results.indexOf(result); + if (index < 0) { + console.error("Failed to find the selected result in the results"); + return; + } + + queryContext.results.splice(index, 1); + this.notify(NOTIFICATIONS.QUERY_RESULT_REMOVED, index); + } + + /** + * Clear the previous query context cache. + */ + clearLastQueryContextCache() { + this._lastQueryContextWrapper = null; + } + + /** + * Notifies listeners of results. + * + * @param {string} name Name of the notification. + * @param {object} params Parameters to pass with the notification. + */ + notify(name, ...params) { + for (let listener of this._listeners) { + // Can't use "in" because some tests proxify these. + if (typeof listener[name] != "undefined") { + try { + listener[name](...params); + } catch (ex) { + console.error(ex); + } + } + } + } +} + +/** + * Tracks and records telemetry events for the given category, if provided, + * otherwise it's a no-op. + * It is currently designed around the "urlbar" category, even if it can + * potentially be extended to other categories. + * To record an event, invoke start() with a starting event, then either + * invoke record() with a final event, or discard() to drop the recording. + * + * @see Events.yaml + */ +class TelemetryEvent { + constructor(controller, category) { + this._controller = controller; + this._category = category; + this._isPrivate = controller.input.isPrivate; + this.#exposureResultTypes = new Set(); + this.#beginObservingPingPrefs(); + } + + /** + * Start measuring the elapsed time from a user-generated event. + * After this has been invoked, any subsequent calls to start() are ignored, + * until either record() or discard() are invoked. Thus, it is safe to keep + * invoking this on every input event as the user is typing, for example. + * + * @param {event} event A DOM event. + * @param {string} [searchString] Pass a search string related to the event if + * you have one. The event by itself sometimes isn't enough to + * determine the telemetry details we should record. + * @throws This should never throw, or it may break the urlbar. + * @see {@link https://firefox-source-docs.mozilla.org/browser/urlbar/telemetry.html} + */ + start(event, searchString = null) { + if (this._startEventInfo) { + if (this._startEventInfo.interactionType == "topsites") { + // If the most recent event came from opening the results pane with an + // empty string replace the interactionType (that would be "topsites") + // with one for the current event to better measure the user flow. + this._startEventInfo.interactionType = this._getStartInteractionType( + event, + searchString + ); + this._startEventInfo.searchString = searchString; + } else if ( + this._startEventInfo.interactionType == "returned" && + (!searchString || + this._startEventInfo.searchString[0] != searchString[0]) + ) { + // In case of a "returned" interaction ongoing, the user may either + // continue the search, or restart with a new search string. In that case + // we want to change the interaction type to "restarted". + // Detecting all the possible ways of clearing the input would be tricky, + // thus this makes a guess by just checking the first char matches; even if + // the user backspaces a part of the string, we still count that as a + // "returned" interaction. + this._startEventInfo.interactionType = "restarted"; + } + + // start is invoked on a user-generated event, but we only count the first + // one. Once an engagement or abandoment happens, we clear _startEventInfo. + return; + } + + if (!this._category) { + return; + } + if (!event) { + console.error("Must always provide an event"); + return; + } + const validEvents = [ + "click", + "command", + "drop", + "input", + "keydown", + "mousedown", + "tabswitch", + "focus", + ]; + if (!validEvents.includes(event.type)) { + console.error("Can't start recording from event type: ", event.type); + return; + } + + this._startEventInfo = { + timeStamp: event.timeStamp || Cu.now(), + interactionType: this._getStartInteractionType(event, searchString), + searchString, + }; + + let { queryContext } = this._controller._lastQueryContextWrapper || {}; + + this._controller.manager.notifyEngagementChange( + this._isPrivate, + "start", + queryContext, + {}, + this._controller.browserWindow + ); + } + + /** + * Record an engagement telemetry event. + * When the user picks a result from a search through the mouse or keyboard, + * an engagement event is recorded. If instead the user abandons a search, by + * blurring the input field, an abandonment event is recorded. + * + * On return, `details.isSessionOngoing` will be set to true if the engagement + * did not end the search session. Not all engagements end the session. The + * session remains ongoing when certain commands are picked (like dismissal) + * and results that enter search mode are picked. + * + * @param {event} [event] + * A DOM event. + * Note: event can be null, that usually happens for paste&go or drop&go. + * If there's no _startEventInfo this is a no-op. + * @param {object} details An object describing action details. + * @param {string} [details.searchString] The user's search string. Note that + * this string is not sent with telemetry data. It is only used + * locally to discern other data, such as the number of characters and + * words in the string. + * @param {string} [details.selType] type of the selected element, undefined + * for "blur". One of "unknown", "autofill", "visiturl", "bookmark", + * "help", "history", "keyword", "searchengine", "searchsuggestion", + * "switchtab", "remotetab", "extension", "oneoff", "dismiss". + * @param {UrlbarResult} [details.result] The engaged result. This should be + * set to the result related to the picked element. + * @param {DOMElement} [details.element] The picked view element. + */ + record(event, details) { + this.clearPauseImpressionTimer(); + + // This should never throw, or it may break the urlbar. + try { + this._internalRecord(event, details); + } catch (ex) { + console.error("Could not record event: ", ex); + } finally { + // Reset the start event info except for engagements that do not end the + // search session. In that case, the view stays open and further + // engagements are possible and should be recorded when they occur. + // (`details.isSessionOngoing` is not a param; rather, it's set by + // `_internalRecord()`.) + if (!details.isSessionOngoing) { + this._startEventInfo = null; + this._discarded = false; + } + } + } + + /** + * Clear the pause impression timer started by startPauseImpressionTimer(). + */ + clearPauseImpressionTimer() { + lazy.clearTimeout(this._pauseImpressionTimer); + } + + /** + * Start a timer that records the pause impression telemetry for given context. + * The telemetry will be recorded after + * "browser.urlbar.searchEngagementTelemetry.pauseImpressionIntervalMs" ms. + * If want to clear this timer, please use clearPauseImpressionTimer(). + * + * @param {UrlbarQueryContext} queryContext + * The query details that will be recorded as pause impression telemetry. + * @param {string} searchSource + * The seach source that will be recorded as pause impression telemetry. + */ + startPauseImpressionTimer(queryContext, searchSource) { + if (this._impressionStartEventInfo === this._startEventInfo) { + // Already took an impression telemetry for this session. + return; + } + + this.clearPauseImpressionTimer(); + this._pauseImpressionTimer = lazy.setTimeout(() => { + let { numChars, numWords, searchWords } = this._parseSearchString( + queryContext.searchString + ); + this._recordSearchEngagementTelemetry( + queryContext, + "impression", + this._startEventInfo, + { + reason: "pause", + numChars, + numWords, + searchWords, + searchSource, + } + ); + + this._impressionStartEventInfo = this._startEventInfo; + }, lazy.UrlbarPrefs.get("searchEngagementTelemetry.pauseImpressionIntervalMs")); + } + + _internalRecord(event, details) { + const startEventInfo = this._startEventInfo; + + if (!this._category || !startEventInfo) { + if (this._discarded && this._category && details?.selType !== "dismiss") { + let { queryContext } = this._controller._lastQueryContextWrapper || {}; + this._controller.manager.notifyEngagementChange( + this._isPrivate, + "discard", + queryContext, + {}, + this._controller.browserWindow + ); + } + return; + } + if ( + !event && + startEventInfo.interactionType != "pasted" && + startEventInfo.interactionType != "dropped" + ) { + // If no event is passed, we must be executing either paste&go or drop&go. + throw new Error("Event must be defined, unless input was pasted/dropped"); + } + if (!details) { + throw new Error("Invalid event details: " + details); + } + + let action; + let skipLegacyTelemetry = false; + if (!event) { + action = + startEventInfo.interactionType == "dropped" ? "drop_go" : "paste_go"; + } else if (event.type == "blur") { + action = "blur"; + } else if ( + details.element?.dataset.command && + // The "help" selType is recognized by legacy telemetry, and `action` + // should be set to either "click" or "enter" depending on whether the + // event is a mouse event, so ignore "help" here. + details.element.dataset.command != "help" + ) { + action = details.element.dataset.command; + skipLegacyTelemetry = true; + } else if (details.selType == "dismiss") { + action = "dismiss"; + skipLegacyTelemetry = true; + } else if (MouseEvent.isInstance(event)) { + action = event.target.id == "urlbar-go-button" ? "go_button" : "click"; + } else { + action = "enter"; + } + + let method = action == "blur" ? "abandonment" : "engagement"; + + if (method == "engagement") { + // Not all engagements end the search session. The session remains ongoing + // when certain commands are picked (like dismissal) and results that + // enter search mode are picked. We should find a generalized way to + // determine this instead of listing all the cases like this. + details.isSessionOngoing = !!( + ["dismiss", "inaccurate_location", "show_less_frequently"].includes( + details.selType + ) || details.result?.payload.providesSearchMode + ); + } + + // numWords is not a perfect measurement, since it will return an incorrect + // value for languages that do not use spaces or URLs containing spaces in + // its query parameters, for example. + let { numChars, numWords, searchWords } = this._parseSearchString( + details.searchString + ); + + details.provider = details.result?.providerName; + details.selIndex = details.result?.rowIndex ?? -1; + + let { queryContext } = this._controller._lastQueryContextWrapper || {}; + + this._recordSearchEngagementTelemetry( + queryContext, + method, + startEventInfo, + { + action, + numChars, + numWords, + searchWords, + provider: details.provider, + searchSource: details.searchSource, + searchMode: details.searchMode, + selectedElement: details.element, + selIndex: details.selIndex, + selType: details.selType, + } + ); + + if (skipLegacyTelemetry) { + this._controller.manager.notifyEngagementChange( + this._isPrivate, + method, + queryContext, + details, + this._controller.browserWindow + ); + return; + } + + if (action == "go_button") { + // Fall back since the conventional telemetry dones't support "go_button" action. + action = "click"; + } + + let endTime = (event && event.timeStamp) || Cu.now(); + let startTime = startEventInfo.timeStamp || endTime; + // Synthesized events in tests may have a bogus timeStamp, causing a + // subtraction between monotonic and non-monotonic timestamps; that's why + // abs is necessary here. It should only happen in tests, anyway. + let elapsed = Math.abs(Math.round(endTime - startTime)); + + // Rather than listening to the pref, just update status when we record an + // event, if the pref changed from the last time. + let recordingEnabled = lazy.UrlbarPrefs.get("eventTelemetry.enabled"); + if (this._eventRecordingEnabled != recordingEnabled) { + this._eventRecordingEnabled = recordingEnabled; + Services.telemetry.setEventRecordingEnabled("urlbar", recordingEnabled); + } + + let extra = { + elapsed: elapsed.toString(), + numChars, + numWords, + }; + + if (method == "engagement") { + extra.selIndex = details.selIndex.toString(); + extra.selType = details.selType; + extra.provider = details.provider || ""; + } + + // We invoke recordEvent regardless, if recording is disabled this won't + // report the events remotely, but will count it in the event_counts scalar. + Services.telemetry.recordEvent( + this._category, + method, + action, + startEventInfo.interactionType, + extra + ); + + Services.telemetry.scalarAdd( + method == "engagement" + ? TELEMETRY_SCALAR_ENGAGEMENT + : TELEMETRY_SCALAR_ABANDONMENT, + 1 + ); + + if ( + method === "engagement" && + queryContext?.view?.visibleResults?.[0]?.autofill + ) { + // Record autofill impressions upon engagement. + const type = lazy.UrlbarUtils.telemetryTypeFromResult( + queryContext.view.visibleResults[0] + ); + Services.telemetry.scalarAdd(`urlbar.impression.${type}`, 1); + } + + this._controller.manager.notifyEngagementChange( + this._isPrivate, + method, + queryContext, + details, + this._controller.browserWindow + ); + } + + _recordSearchEngagementTelemetry( + queryContext, + method, + startEventInfo, + { + action, + numWords, + numChars, + provider, + reason, + searchWords, + searchSource, + searchMode, + selectedElement, + selIndex, + selType, + } + ) { + const browserWindow = this._controller.browserWindow; + let sap = "urlbar"; + if (searchSource === "urlbar-handoff") { + sap = "handoff"; + } else if ( + browserWindow.isBlankPageURL(browserWindow.gBrowser.currentURI.spec) + ) { + sap = "urlbar_newtab"; + } else if (browserWindow.gBrowser.currentURI.schemeIs("moz-extension")) { + sap = "urlbar_addonpage"; + } + + searchMode = searchMode ?? this._controller.input.searchMode; + + // Distinguish user typed search strings from persisted search terms. + const interaction = this.#getInteractionType( + method, + startEventInfo, + searchSource, + searchWords, + searchMode + ); + const search_mode = this.#getSearchMode(searchMode); + const currentResults = queryContext?.view?.visibleResults ?? []; + let numResults = currentResults.length; + let groups = currentResults + .map(r => lazy.UrlbarUtils.searchEngagementTelemetryGroup(r)) + .join(","); + let results = currentResults + .map(r => lazy.UrlbarUtils.searchEngagementTelemetryType(r)) + .join(","); + + let eventInfo; + if (method === "engagement") { + const selected_result = lazy.UrlbarUtils.searchEngagementTelemetryType( + currentResults[selIndex], + selType + ); + const selected_result_subtype = + lazy.UrlbarUtils.searchEngagementTelemetrySubtype( + currentResults[selIndex], + selectedElement + ); + + if (selected_result === "input_field" && !queryContext?.view?.isOpen) { + numResults = 0; + groups = ""; + results = ""; + } + + eventInfo = { + sap, + interaction, + search_mode, + n_chars: numChars, + n_words: numWords, + n_results: numResults, + selected_result, + selected_result_subtype, + provider, + engagement_type: + selType === "help" || selType === "dismiss" ? selType : action, + groups, + results, + }; + } else if (method === "abandonment") { + eventInfo = { + sap, + interaction, + search_mode, + n_chars: numChars, + n_words: numWords, + n_results: numResults, + groups, + results, + }; + } else if (method === "impression") { + eventInfo = { + reason, + sap, + interaction, + search_mode, + n_chars: numChars, + n_words: numWords, + n_results: numResults, + groups, + results, + }; + } else { + console.error(`Unknown telemetry event method: ${method}`); + return; + } + + // First check to see if we can record an exposure event + if ( + (method === "abandonment" || method === "engagement") && + this.#exposureResultTypes.size + ) { + const exposureResults = Array.from(this.#exposureResultTypes).join(","); + this._controller.logger.debug( + `exposure event: ${JSON.stringify({ results: exposureResults })}` + ); + Glean.urlbar.exposure.record({ results: exposureResults }); + + // reset the provider list on the controller + this.#exposureResultTypes.clear(); + } + + this._controller.logger.info( + `${method} event: ${JSON.stringify(eventInfo)}` + ); + + Glean.urlbar[method].record(eventInfo); + } + + /** + * Add result type to engagementEvent instance exposureResultTypes Set. + * + * @param {UrlbarResult} result UrlbarResult to have exposure recorded. + */ + addExposure(result) { + if (result.exposureResultType) { + this.#exposureResultTypes.add(result.exposureResultType); + } + } + + #getInteractionType( + method, + startEventInfo, + searchSource, + searchWords, + searchMode + ) { + if (searchMode?.entry === "topsites_newtab") { + return "topsite_search"; + } + + let interaction = startEventInfo.interactionType; + if ( + (interaction === "returned" || interaction === "restarted") && + this._isRefined(new Set(searchWords), this.#previousSearchWordsSet) + ) { + interaction = "refined"; + } + + if (searchSource === "urlbar-persisted") { + switch (interaction) { + case "returned": { + interaction = "persisted_search_terms"; + break; + } + case "restarted": + case "refined": { + interaction = `persisted_search_terms_${interaction}`; + break; + } + } + } + + if ( + (method === "engagement" && + lazy.UrlbarPrefs.isPersistedSearchTermsEnabled()) || + method === "abandonment" + ) { + this.#previousSearchWordsSet = new Set(searchWords); + } else if (method === "engagement") { + this.#previousSearchWordsSet = null; + } + + return interaction; + } + + #getSearchMode(searchMode) { + if (!searchMode) { + return ""; + } + + if (searchMode.engineName) { + return "search_engine"; + } + + const source = lazy.UrlbarUtils.LOCAL_SEARCH_MODES.find( + m => m.source == searchMode.source + )?.telemetryLabel; + return source ?? "unknown"; + } + + _parseSearchString(searchString) { + let numChars = searchString.length.toString(); + let searchWords = searchString + .substring(0, lazy.UrlbarUtils.MAX_TEXT_LENGTH) + .trim() + .split(lazy.UrlbarTokenizer.REGEXP_SPACES) + .filter(t => t); + let numWords = searchWords.length.toString(); + + return { + numChars, + numWords, + searchWords, + }; + } + + /** + * Checks whether re-searched by modifying some of the keywords from the + * previous search. Concretely, returns true if there is intersects between + * both keywords, otherwise returns false. Also, returns false even if both + * are the same. + * + * @param {Set} currentSet The current keywords. + * @param {Set} [previousSet] The previous keywords. + * @returns {boolean} true if current searching are refined. + */ + _isRefined(currentSet, previousSet = null) { + if (!previousSet) { + return false; + } + + const intersect = (setA, setB) => { + let count = 0; + for (const word of setA.values()) { + if (setB.has(word)) { + count += 1; + } + } + return count > 0 && count != setA.size; + }; + + return ( + intersect(currentSet, previousSet) || intersect(previousSet, currentSet) + ); + } + + _getStartInteractionType(event, searchString) { + if (event.interactionType) { + return event.interactionType; + } else if (event.type == "input") { + return lazy.UrlbarUtils.isPasteEvent(event) ? "pasted" : "typed"; + } else if (event.type == "drop") { + return "dropped"; + } else if (searchString) { + return "typed"; + } + return "topsites"; + } + + /** + * Resets the currently tracked user-generated event that was registered via + * start(), so it won't be recorded. If there's no tracked event, this is a + * no-op. + */ + discard() { + this.clearPauseImpressionTimer(); + if (this._startEventInfo) { + this._startEventInfo = null; + this._discarded = true; + } + } + + /** + * Extracts a telemetry type from a result and the element being interacted + * with for event telemetry. + * + * @param {object} result The element to analyze. + * @param {Element} element The element to analyze. + * @returns {string} a string type for the telemetry event. + */ + typeFromElement(result, element) { + if (!element) { + return "none"; + } + if ( + element.classList.contains("urlbarView-button-help") || + element.dataset.command == "help" + ) { + return result?.type == lazy.UrlbarUtils.RESULT_TYPE.TIP + ? "tiphelp" + : "help"; + } + if ( + element.classList.contains("urlbarView-button-block") || + element.dataset.command == "dismiss" + ) { + return "block"; + } + // Now handle the result. + return lazy.UrlbarUtils.telemetryTypeFromResult(result); + } + + /** + * Reset the internal state. This function is used for only when testing. + */ + reset() { + this.#previousSearchWordsSet = null; + } + + #PING_PREFS = { + maxRichResults: Glean.urlbar.prefMaxResults, + "suggest.topsites": Glean.urlbar.prefSuggestTopsites, + }; + + #beginObservingPingPrefs() { + for (const p of Object.keys(this.#PING_PREFS)) { + this.onPrefChanged(p); + } + lazy.UrlbarPrefs.addObserver(this); + } + + onPrefChanged(pref) { + const metric = this.#PING_PREFS[pref]; + if (metric) { + metric.set(lazy.UrlbarPrefs.get(pref)); + } + } + + #previousSearchWordsSet = null; + + #exposureResultTypes; +} |