User Actions¶
A subset of actions are available to messages via fields like button_action
for snippets, or primary_action
for CFRs.
Usage¶
For snippets, you should add the action type in button_action
and any additional parameters in `button_action_args. For example:
{
"button_action": "OPEN_ABOUT_PAGE",
"button_action_args": "config"
}
Available Actions¶
OPEN_FIREFOX_VIEW
¶
args: (none)
Opens the Firefox View pseudo-tab.
OPEN_PRIVATE_BROWSER_WINDOW
¶
args: (none)
Opens a new private browsing window.
OPEN_URL
¶
args:
string
(a url)
Opens a given url.
Example:
{
"button_action": "OPEN_URL",
"button_action_args": "https://foo.com"
}
OPEN_ABOUT_PAGE
¶
args:
{
args: string, // (a valid about page without the `about:` prefix)
entrypoint?: string, // URL search param used for referrals
}
Opens a given about page
Example:
{
"button_action": "OPEN_ABOUT_PAGE",
"button_action_args": "config"
}
OPEN_PREFERENCES_PAGE
¶
args:
{
args?: string, // (a category accessible via a `#`)
entrypoint?: string // URL search param used to referrals
Opens `about:preferences` with an optional category accessible via a `#` in the URL (e.g. `about:preferences#home`).
Example:
```json
{
"button_action": "OPEN_PREFERENCES_PAGE",
"button_action_args": "home"
}
SHOW_FIREFOX_ACCOUNTS
¶
args: (none)
Opens Firefox accounts sign-up page. Encodes some information that the origin was from snippets by default.
FXA_SIGNIN_FLOW
¶
args:
{
// a valid `where` value for `openUILinkIn`. Only `tab` and `window` have been tested, and `tabshifted`
// is unlikely to do anything different from `tab`.
where?: "tab" | "window" = "tab",
entrypoint?: string // URL search params string to pass along to FxA. Defaults to "activity-stream-firstrun".
extraParams?: object // Extra parameters to pass along to FxA. See FxAccountsConfig.promiseConnectAccountURI.
}
Opens a Firefox accounts sign-up or sign-in page, and does the work of closing the resulting tab or window once
sign-in completes. Returns a Promise that resolves to true
if sign-in succeeded, or to false
if the sign-in
window or tab closed before sign-in could be completed.
Encodes some information that the origin was from about:welcome by default.
SHOW_MIGRATION_WIZARD
¶
args: (none)
Opens import wizard to bring in settings and data from another browser.
PIN_CURRENT_TAB
¶
args: (none)
Pins the currently focused tab.
ENABLE_FIREFOX_MONITOR
¶
args:
{
url: string;
flowRequestParams: {
entrypoint: string;
utm_term: string;
form_type: string;
}
}
Opens an oauth flow to enable Firefox Monitor at a given url
and adds Firefox metrics that user given a set of flowRequestParams
.
url
¶
The URL should start with https://monitor.firefox.com/oauth/init
and add various metrics tags as search params, including:
utm_source
utm_campaign
form_type
entrypoint
You should verify the values of these search params with whoever is doing the data analysis (e.g. Leif Oines).
flowRequestParams
¶
These params are used by Firefox to add information specific to that individual user to the final oauth URL. You should include:
entrypoint
utm_term
form_type
The entrypoint
and form_type
values should match the encoded values in your url
.
You should verify the values with whoever is doing the data analysis (e.g. Leif Oines).
Example¶
{
"button_action": "ENABLE_FIREFOX_MONITOR",
"button_action_args": {
"url": "https://monitor.firefox.com/oauth/init?utm_source=snippets&utm_campaign=monitor-snippet-test&form_type=email&entrypoint=newtab",
"flowRequestParams": {
"entrypoint": "snippets",
"utm_term": "monitor",
"form_type": "email"
}
}
}
HIGHLIGHT_FEATURE
¶
Can be used to highlight (show a light blue overlay) a certain button or part of the browser UI.
args:
string
a valid targeting defined in the UITour
INSTALL_ADDON_FROM_URL
¶
Can be used to install an addon from addons.mozilla.org.
args:
{
url: string,
telemetrySource?: string
};
OPEN_PROTECTION_REPORT
¶
Opens about:protections
OPEN_PROTECTION_PANEL
¶
Opens the protection panel behind on the lock icon of the awesomebar
DISABLE_STP_DOORHANGERS
¶
Disables all Social Tracking Protection messages
args: (none)
OPEN_AWESOME_BAR
¶
Focuses and expands the awesome bar.
args: (none)
CANCEL
¶
No-op action used to dismiss CFR notifications (but not remove or block them)
args: (none)
DISABLE_DOH
¶
User action for turning off the DoH feature
args: (none)
ACCEPT_DOH
¶
User action for continuing to use the DoH feature
args: (none)
CONFIGURE_HOMEPAGE
¶
Action for configuring the user homepage and restoring defaults.
args:
{
homePage: "default" | null;
newtab: "default" | null;
layout: {
search: boolean;
topsites: boolean;
highlights: boolean;
topstories: boolean;
snippets: boolean;
}
}
PIN_FIREFOX_TO_TASKBAR
¶
Action for pinning Firefox to the user’s taskbar.
args: (none)
SET_DEFAULT_BROWSER
¶
Action for setting the default browser to Firefox on the user’s system.
args: (none)
SET_DEFAULT_PDF_HANDLER
¶
Action for setting the default PDF handler to Firefox on the user’s system.
Windows only.
args:
{
// Only set Firefox as the default PDF handler if the current PDF handler is a
// known browser.
onlyIfKnownBrowser?: boolean;
}
SHOW_SPOTLIGHT
¶
Action for opening a spotlight tab or window modal using the content passed to the dialog.
BLOCK_MESSAGE
¶
Disable a message by adding to an indexedDb list of blocked messages
args:
string
id of the message
SET_PREF
¶
Action for setting various browser prefs
Prefs that can be changed with this action are:
browser.dataFeatureRecommendations.enabled
browser.privateWindowSeparation.enabled
browser.startup.homepage
cookiebanners.service.mode
cookiebanners.service.mode.privateBrowsing
Alternatively, if a pref is set with this action and is not present in the list
above, it will be created and prepended with messaging-system-action.
.
args:
{
pref: {
name: string;
value: string | boolean | number;
}
}
MULTI_ACTION
¶
Action for running multiple actions. Actions should be included in an array of actions.
args:
{
actions: Array<UserAction>
}
example:
{
"button_action": "MULTI_ACTION",
"button_action_args": {
"actions": [
{
"type": "OPEN_URL",
"args": "https://www.example.com"
},
{
"type": "OPEN_AWESOME_BAR"
}
]
}
}
CLICK_ELEMENT
¶
args:
string
A CSS selector for the HTML element to be clicked
Selects an element in the current Window’s document and triggers a click action
RELOAD_BROWSER
¶
args: (none)
Action for reloading the current browser.