UITour library API

This is the web API provided by the library UITour-lib.js for use by web content with appropriate permissions.

class Mozilla.UITour()

Library that exposes an event-based Web API for communicating with the desktop browser chrome. It can be used for tasks such as opening menu panels and highlighting the position of buttons in the toolbar.

For security/privacy reasons Mozilla.UITour will only work on a list of allowed secure origins. The list of allowed origins can be found in https://searchfox.org/mozilla-central/source/browser/app/permissions.

static Mozilla.UITour.ConfigurationName()

Valid values:

static Mozilla.UITour.HighlightEffect()

Valid values:

  • random

  • wobble

  • zoom

  • color

Generate using the following in the Browser Console:

[...UITour.highlightEffects].join("\n* - ")

See also

static Mozilla.UITour.MenuName()

Valid values:

  • appMenu

  • bookmarks

  • pocket

See also

static Mozilla.UITour.Target()

Valid values:

  • accountStatus

  • addons

  • appMenu

  • backForward

  • bookmarks

  • forget

  • help

  • home

  • logins

  • pageAction-bookmark

  • pocket

  • privateWindow

  • quit

  • readerMode-urlBar

  • search

  • searchIcon

  • selectedTabIcon

  • urlbar

Generate using the following in the Browser Console:

[...UITour.targets.keys()].join("\n* - ")

See also

static Mozilla.UITour.addNavBarWidget(name, callback)

Add the specified customizable widget to the navigation toolbar.

Arguments:

  • name (Mozilla.UITour.Target) – Identifier of the customizable widget.

  • callback (function) – Called with no arguments once the icon was successfully added to the toolbar. Not called if it doesn’t succeed.

Examples:

Mozilla.UITour.addNavBarWidget('forget', function () {
  console.log('forget button added to toolbar');
});
static Mozilla.UITour.closeTab()

The last tab in the current window will never be closed, in which case this call will have no effect. The calling code is expected to take an action after a small timeout in order to handle this case, for example by displaying a goodbye message or a button to restart the tour.

static Mozilla.UITour.forceShowReaderIcon()

This is useful if you want to target an annotation (panel/highlight) on it but the tour page doesn’t have much textual content.

static Mozilla.UITour.getConfiguration(configName, callback)

Retrieve some information about the application/profile.

Arguments:

  • configName (Mozilla.UITour.ConfigurationName) – Name of configuration to retrieve

  • callback (function) – Called with one argument containing the value of the configuration.

static Mozilla.UITour.getTreatmentTag(name, callback)

Retrieved the value for a set FHR treatment tag.

Arguments:

  • name (string) – Tag name to be retrieved

  • callback (function) – Called once the data has been retrieved

Examples:

Mozilla.UITour.getTreatmentTag('srch-chg-action', function(value) {
  console.log(value);
});

See also

static Mozilla.UITour.hideHighlight()

Hide any visible UI highlight.

See also

static Mozilla.UITour.hideInfo()

Hide any visible info panels.

See also

static Mozilla.UITour.hideMenu(name)

Close the named application menu.

Arguments:

See also

static Mozilla.UITour.observe(listener, callback)

There can only be one observer per tour tab so calling this a second time will replace any previous listener. To remove an observer, call the method with null as the first argument.

Arguments:

  • listener (function) – Called when any UITour notification occurs.

  • callback (function) – Called when the browser acknowledges the observer.

static Mozilla.UITour.openPreferences(pane)
Arguments:

  • pane (string) – Pane to open/switch the preferences to. Valid values match fragments on about:preferences and are subject to change e.g.: For the Preferences: - general - applications - sync - privacy - advanced To open to the options of sending telemetry, health report, crash reports, that is, the privacy pane > reports on the preferences. Please call Mozilla.UITour.openPreferences(“privacy-reports”). UITour would do route mapping automatically.

static Mozilla.UITour.openSearchPanel(callback)

This should have been implemented via showMenu(“search”, …).

Arguments:

  • callback (function) – Called once the panel has opened.

static Mozilla.UITour.ping(callback)

Ensure the browser is ready to handle this document as a tour.

Arguments:

  • callback (function) – Callback to call if UITour is working for the document.

static Mozilla.UITour.registerPageID(pageID)

Register an identifier to use in Telemetry. pageID must be a string unique to the page/tour.

Arguments:

  • pageID (string) – Unique identifier for the page/tour.

Examples:

Mozilla.UITour.registerPageID('firstrun-page-firefox-29');
static Mozilla.UITour.resetFirefox()

Show a profile refresh/reset dialog, allowing users to choose to reomve add-ons and customizations as well as restore browser defaults, if possible. getConfiguration(‘canReset’) should first be used to determine whether Refresh/Reset is possible for the user’s build/profile.

See also

static Mozilla.UITour.setConfiguration(configName, configValue)

Set some value or take some action.

Valid configuration names:

defaultBrowser

Try to set the application as the default web browser. Since Fx40

Arguments:

  • configName (string) – Configuration name to set (e.g. “defaultBrowser”)

  • configValue (string|number|boolean) – Not currently used

Examples:

Mozilla.UITour.setConfiguration('defaultBrowser');
static Mozilla.UITour.setDefaultSearchEngine(identifier)

Set the specified search engine as the user-set default.

See https://searchfox.org/mozilla-release/source/browser/locales/search/list.json

Arguments:

  • identifier (string) – Identifier of the engine (e.g. ‘yahoo’).

See also

static Mozilla.UITour.setSearchTerm(term)

Set the search term in the search box.

This should have been implemented via setConfiguration(“searchTerm”, …).

Arguments:

  • term (string) – Search string e.g. ‘Firefox’

static Mozilla.UITour.setTreatmentTag(name, value)

Sets a key+value pair as a treatment tag for recording in FHR.

Arguments:

  • name (string) – tag name for the treatment

  • value (string) – tag value for the treatment

Examples:

Mozilla.UITour.setTreatmentTag('srch-chg-action', 'Switch');

See also

static Mozilla.UITour.showConnectAnotherDevice(extraURLParams)

Request the browser open the “Connect Another Device” Firefox Accounts page.

Arguments:

  • extraURLParams (object) – An object containing additional parameters for the URL opened by the browser for reasons of promotional campaign tracking. Each attribute of the object must have a name that is a string, is “flow_id”, “flow_begin_time”, “device_id” or begins with utm_ and contains only only alphanumeric characters, dashes or underscores. The values may be any string and will automatically be encoded. For Flow metrics, see details at https://mozilla.github.io/ecosystem-platform/docs/fxa-engineering/fxa-metrics#content-server

Examples:

// Will open https://accounts.firefox.com/connect_another_device?entrypoint=uitour
Mozilla.UITour.showConnectAnotherDevice();

// Will open:
// https://accounts.firefox.com/connect_another_device?entrypoint=uitour&utm_foo=bar&utm_bar=baz
Mozilla.UITour.showConnectAnotherDevice({
  'utm_foo': 'bar',
  'utm_bar': 'baz'
});
static Mozilla.UITour.showFirefoxAccounts(extraURLParams, entrypoint, email)

Request the browser open the Firefox Accounts page.

Arguments:

  • extraURLParams (object) – An object containing additional parameters for the URL opened by the browser for reasons of promotional campaign tracking. Each attribute of the object must have a name that is a string, is “flow_id”, “flow_begin_time”, “device_id” or begins with utm_ and contains only only alphanumeric characters, dashes or underscores. The values may be any string and will automatically be encoded. For Flow metrics, see details at https://mozilla.github.io/ecosystem-platform/docs/fxa-engineering/fxa-metrics#content-server

  • entrypoint (string) – A string containing the entrypoint name.

  • email (string) – A string containing the default email account for the URL opened by the browser.

Examples:

// Will open https://accounts.firefox.com/signup?entrypoint=uitour
Mozilla.UITour.showFirefoxAccounts();

// Will open:
// https://accounts.firefox.com/signup?entrypoint=uitour&utm_foo=bar&utm_bar=baz
Mozilla.UITour.showFirefoxAccounts({
  'utm_foo': 'bar',
  'utm_bar': 'baz'
});

// Will open:
// https://accounts.firefox.com/?action=email&email=foo%40bar.com&entrypoint=uitour
Mozilla.UITour.showFirefoxAccounts(null, null, "foo@bar.com");

// Will open:
// https://accounts.firefox.com/signup?entrypoint=sample
Mozilla.UITour.showFirefoxAccounts(null, "sample");

// Will open:
// https://accounts.firefox.com/?action=email&email=foo%40bar.com&entrypoint=uitour&flow_id=c5b5ad7c4a94462afe4b9a7fbcca263dbd6c8409fb4539449c50c4a52544b2ed&flow_begin_time=1590680755812
Mozilla.UITour.showFirefoxAccounts({
  flow_id: 'c5b5ad7c4a94462afe4b9a7fbcca263dbd6c8409fb4539449c50c4a52544b2ed',
  flow_begin_time: 1590680755812,
  device_id: '7e450f3337d3479b8582ea1c9bb5ba6c'
}, "foo@bar.com");
static Mozilla.UITour.showHighlight(target, effect="none")

Visually highlight a UI widget.

Arguments:

Examples:

Mozilla.UITour.showHighlight('appMenu', 'wobble');

See also

static Mozilla.UITour.showInfo(target, title, text, icon="null", buttons=[], buttons[], options={})

Show an arrow panel with optional images and buttons anchored at a specific UI target.

Arguments:

  • target (Mozilla.UITour.Target) – Identifier of the UI widget to anchor the panel at.

  • title (string) – Title text to be shown as the heading of the panel.

  • text (string) – Body text of the panel.

  • icon (string) – URL of a 48x48px (96px @ 2dppx) image (which will be resolved relative to the tab’s URI) to display in the panel.

  • buttons (Array.<object>) – Array of objects describing buttons.

  • buttons[].label (string) – Button label

  • buttons[].icon (string) – Button icon URL

  • buttons[].style (string) – Button style (“primary” or “link”)

  • buttons[].callback (function) – Called when the button is clicked

  • options (object) – Advanced options

  • options.closeButtonCallback (function) – Called when the panel’s close button is clicked.

Examples:

var buttons = [
  {
    label: 'Cancel',
    style: 'link',
    callback: cancelBtnCallback
  },
  {
    label: 'Confirm',
    style: 'primary',
    callback: confirmBtnCallback
  }
];

var icon = '//mozorg.cdn.mozilla.net/media/img/firefox/australis/logo.png';

var options = {
  closeButtonCallback: closeBtnCallback
};

Mozilla.UITour.showInfo('appMenu', 'my title', 'my text', icon, buttons, options);

See also

static Mozilla.UITour.showMenu(name, callback)

Open the named application menu.

Arguments:

  • name (Mozilla.UITour.MenuName) – Menu name

  • callback (function) – Callback to be called with no arguments when the menu opens.

Examples:

Mozilla.UITour.showMenu('appMenu', function() {
  console.log('menu was opened');
});

See also

static Mozilla.UITour.showNewTab()

Loads about:newtab in the tour tab.

static Mozilla.UITour.showProtectionReport()

Loads about:protections in the tour tab.

static Mozilla.UITour.toggleReaderMode()

Toggle into reader mode for the current tab. Once the user enters reader mode, the UITour document will not be active and therefore cannot call other UITour APIs.

class Mozilla.UITour.Configuration()
static Mozilla.UITour.Configuration.AccountService()

Information about an account service

Arguments:

  • id (string) – The service ID. A list of attached service IDs can be found on our telemetry documentation site.

  • lastAccessedWeeksAgo (number) – How many weeks ago the service was accessed by this account.

static Mozilla.UITour.Configuration.AccountServices()

Information about clients attached to the account. An object. The key is a string ID of the attached service. A list of attached service IDs can be found on our telemetry documentation site. The value is a Mozilla.UITour.Configuration.AccountService()

static Mozilla.UITour.Configuration.AppInfo()
Arguments:

  • canSetDefaultBrowserInBackground (boolean) – Whether the application can be set as the default browser in the background without user interaction.

  • defaultBrowser (boolean) – Whether the application is the default browser. Since Fx40.

  • defaultUpdateChannel (string) – Update channel e.g. ‘release’, ‘beta’, ‘aurora’, ‘nightly’, ‘default’ (self-built or automated testing builds)

  • distribution (string) – Contains the distributionId property. This value will be “default” in most cases but can differ for repack or funnelcake builds. Since Fx48

  • profileCreatedWeeksAgo (number) – The number of weeks since the profile was created, starting from 0 for profiles dating less than seven days old. Since Fx56.

  • profileResetWeeksAgo (number) – The number of weeks since the profile was last reset, starting from 0 for profiles reset less than seven days ago. If the profile has never been reset it returns null. Since Fx56.

  • version (string) – Version string e.g. “48.0a2”

static Mozilla.UITour.Configuration.AvailableTargets()

Array of UI Targets currently available to be annotated.

static Mozilla.UITour.Configuration.BrowserServices()

Information about a services attached to the browser. All properties are optional and only exist if the service is enabled.

Arguments:
static Mozilla.UITour.Configuration.CanReset()

Indicate whether a user can refresh their Firefox profile via Mozilla.UITour.resetFirefox().

See also

static Mozilla.UITour.Configuration.FxA()

FxA local status, including whether FxA is connected and the general account state.

Arguments:

  • setup (boolean) – Whether FxA is setup on this device. If false, no other properties will exist.

  • accountStateOK (boolean) – Whether the FxA account state is OK. If false, it probably means the account is unverified or the user has changed their password on another device and needs to update it here. In that case many other properties will not exist.

  • browserServices (Mozilla.UITour.Configuration.BrowserServices) – Information about account services attached to this browser, and with special support implemented by this browser. You should not expect every accountService connected in this browser to get a special entry here. Indeed, what services, and in what circumstances they may appear here in the future is largely TBD.

static Mozilla.UITour.Configuration.FxAConnections()

FxA connections status - information about the account which typically isn’t stored locally, so needs to be obtained from the FxA servers. As such, requesting this information is likely to be high-latency and may return incomplete data if there is a network or server error.

Arguments:

  • setup (boolean) – Whether FxA is setup on this device. If false, no other properties will exist.

  • numOtherDevices (number) – Number of devices connected to this account, not counting this device.

  • numDevicesByType (Record.<string, number>) – A count of devices connected to the account by device ‘type’. Valid values for type are defined by the FxA server but roughly correspond to form-factor with values like ‘desktop’, ‘mobile’, ‘vr’, etc.

  • accountServices (Mozilla.UITour.Configuration.AccountServices) – Information about services attached to this account. These services may be enabled on devices or applications external to this browser and should not be confused with devices. For example, if the user has enabled Monitor or Lockwise on one or more devices - including on this device - that service will have a single entry here.

static Mozilla.UITour.Configuration.Search()

From version 34 through 42 inclusive, a string was returned for the ‘selectedSearchEngine’ configuration instead of the object like ‘search’.

Arguments:

  • searchEngineIdentifier (string) – The default engine’s identifier

  • engines (Array.<string>) – Identifiers of visible engines

static Mozilla.UITour.Configuration.Sync()

Sync status and device counts.

Arguments:

  • setup (boolean) – Whether sync is setup

  • desktopDevices (number) – Number of desktop devices

  • mobileDevices (number) – Number of mobile devices

  • totalDevices (number) – Total number of connected devices

See also