WebExtensions API

The WebExtensions API provides a large number of ways to hook into web browsers. We’ll focus only on some of the most commonly used APIs (and the ones I’m most interested in) but you can find a full WebExtensions API reference on MDN.

You’ll also want to take a look at the compatibility chart on MDN to see which browsers have implemented which portions of the API.

  • alarms – Schedule code to run.
  • bookmarks – Create bookmarks, retrieve existing, edit, remove, organize, etc.
  • browserAction – Add a button to the browser toolbar.
  • browserSettings – Allows overriding a number of global browser settings.
  • browsingData – Allows for clearing data such as the cache, cookies, downloads, local storage, etc.
  • commands – Listen for the user executing commands you have registered.
  • contentScripts – Dynamically add/remove scripts to be inserted into pages.
  • cookies – Get, set, and monitor cookies.
  • events – Interact with certain browser events.
  • extension, extensionTypes – Utilities relating to the extension.
  • find – Find text in web page.
  • history – Interact with browser history.
  • i18n – Functions to help with internationalization.
  • identity – Integrates with OAuth2 providers.
  • management – Manage installed add-ons.
  • menus (aka contextMenus) – Allows for modifying browser menus.
  • notifications – Displays OS level notifications.
  • omnibox – Customize behavior of omnibox.
  • permissions – Request additional permissions at runtime.
  • runtime – Allows communicating within one’s extension, to other extensions, and with native applications.
  • search – Executes search with specific search engine.
  • sessions – Allows one to list and restore tabs and windows.
  • sidebarAction – Get and set properties of an extension sidebar.
  • storage – Store, retrieve, and monitor data.
  • tabs – Interact with browser tabs.
  • webNavigation – Add event listeners to the various stages of navigating.
  • webRequest – Add event listeners to the various stages of HTTP requests.
  • windows – Interact with browser windows.

Other APIs include clipboard, contextualIdentities, devtools (.inspectedWindow, .network, .panels), dns, downloads, idle, pkcs11, privacy, proxy, theme, topSites, types, and so on.

Tabs API

This section includes a selection of the Tabs API, mainly focused on areas I’m interested in.

  • Permissions
    • tabs
  • Types
    • Tab
      • active – “Whether the tab is active in its window. Does not necessarily mean the window is focused.”
      • audible – “Whether the tab has produced sound over the past couple of seconds (but it might not be heard if also muted).”
      • autoDiscardable – “Whetehr the tab can be discarded automatically by the browser when resources are low.”
      • discarded – “A discarded tab is one whose content has been unloaded from memory, but is still visible in the tab strip.”
      • groupId
      • id – “Tab IDs are unique within a browser session.”
      • pendingUrl – “The URL the tab is navigating to, before it has committed.”
      • sessionId – “The session ID used to uniquely identify a tab obtained from the sessions API.”
      • status – “The tab’s loading status”
      • title
      • url – “The last committed URL of the main frame of the tab.”
    • TabStatus
      • unloaded
      • loading
      • complete
  • Methods
    • connect – “Connects to the content script(s) in the specified tab.”
    • create – “Creates a new tab.”
    • discard – “Discards a tab from memory….still visible on the tab strip and…reloaded when activated.”
    • duplicate
    • get – “Retrieves details about the specified tab.”
      `chrome.tabs.get(
      tabId: number,
      callback?: function,
      )
      `
    • getCurrent – “Gets the tab that this script call is being made from. Returns undefined if called from a non-tab context…”
    • goBack – “Go back to the previous page”
    • goForward
    • group – “Adds one or more tabs to a specified group”
    • highlight – “Highlights the given tabs and focuses on the first of group.”
    • query – “Gets all tabs that have the specified properties”
      chrome.tabs.query(
      queryInfo: object,
      callback?: function,
      )
      • Parameters: active, audible, autoDiscardable, currentWindow, discarded, groupId, highlighted, index, muted, pinned, status, title, url, windowId
    • reload – “Reload a tab.”
      chrome.tabs.reload(
      tabId?: number,
      reloadProperties?: object,
      callback?: function,
      )
      • reloadProperties takes bypassCache, determining whether local caching is bypassed. Default is false.
    • remove – “Closes one or more tabs.”
    • sendMessage – “Sends a single message to the content script(s) in the specified tab, with an optional callback to run when a response is sent back.”
      chrome.tabs.sendMessage(
      tabId: number,
      message: any,
      options?: object,
      callback?: function,
      )
    • ungroup
    • update – “Modifies the properties of a tab.”
      • updateProperties can include active, autoDiscardable, highlighted, muted, pinned, url
  • Events
    • onActivated – “Fires when the active tab in a window changes.”
    • onAttached -“Fired when a tab is attached to a window…”
    • onCreated – “Fired when a tab is created.”
    • onDetached – “Fired when a tab is detached from a window…”
    • onHighlighted – “Fired when the highlighted or selected tabs in a window changes.”
    • onMoved – “Fired when a tab is moved within a window.”
    • onRemoved – “Fired when a tab is closed.”
    • onReplaced – “Fired when a tab is replaced with another tab due to prerendering or instant.”
      • What does that mean?
    • onUpdated – “Fired when a tab is updated.”
      • Use the callback to process the data returned including tabId, changeInfo, and tab
      • changeInfo includes audible, autoDiscardable, discarded, groupId, mutedInfo, pinned, status, title, url

Action API

This section is focused on areas of the API I am interested in, see above link for comprehensive reference. The action API allows one to control the extension’s icon in the Chrome toolbar.

  • Permissions:
    • action
  • Parts of the UI:
    • Icon
    • Tooltip
    • Badge
    • Popup
  • Methods
    • disable – “Disables the action for a tab.”
    • enable – “By default, actions are enabled.”
    • getBadgeBackgroundColor, getBadgeText, getBadgeTextColor
    • getPopup – “Gets the html document set as the popup for this action.”
    • getTitle – “Gets the title of the action.”
    • getUserSettings
    • isEnabled – “Indicates whether the extension action is enabled for a tab (or globally if no tabId is provided). Actions enabled using only declarativeContent always return false.”
    • openPopup – “Opens the extension’s popup.” (Dev channel)
    • setBadgeBackgroundColor, setBadgeText, setBadgeTextColor
    • setIcon
    • setPopup
    • setTitle
  • Events
    • onClicked

Bookmarks API

As elsewhere, covers what I’m interested in.

  • Permissions:
    • bookmarks
  • Types
    • BookmarkTreeNode – “A node (either a bookmark or a folder) in the bookmark tree. Child nodes are ordered within their parent folder.”
    • Properties:
      • children – “An ordered list of children”
      • dateAdded
      • dateGroupModified
      • dateLastUsed
      • id
      • parentId
      • title
      • url
    • CreateDetails
      • index
      • parentId
      • title
      • url
  • Methods
    • create
    • get
    • getChildren
    • getRecent – “Retrieves the recently added bookmarks.”
    • getSubTree – “Retrieves part of the Bookmarks hierarchy, started at the specified node.”
    • getTree
    • remove
    • removeTree
    • search – “Searches for BookmarkTreeNodes matching the given query.”
    • update – “Updates the properties of a bookmark or folder.”
  • Events
    • onChanged
    • onChildrenReordered
    • onCreated
    • onImportBegan
    • onImportEnded
    • onMoved
    • onRemoved

Alarms API

As elsewhere, this covers only things I’m interested in.

  • Permissions:
    • alarms
  • Types:
    • Alarm
      • Properties:
        • name
        • periodInMinutes
        • scheduledTime
    • AlarmCreateInfo
      • Properties:
        • delayInMinutes – “Length of time in minutes after which the onAlarm event should fire.”
        • periodInMinutes
        • when
  • Methods:
    • clear – “Clears the alarm with the given name.”
    • clearAll – “Clears all alarms.”
    • create – “Creates an alarm.”
    • get – “Retrieves details about the specified alarm.”
    • getAll – “Gets an array of all the alarms.”
  • Events:
    • onAlarm – “Fired when an alarm has elapsed. Useful for event pages.”

browsingData API

Only what I want to talk about. 🙂

  • Permissions:
    • browsingData

Commands API

You get the drill.

  • “Use the commands API to add keyboard shortcuts that trigger actions in your extension…”

contextMenus API

Same old.

  • “Use the…API to add items to Google Chrome’s context menu.”
  • Permissions:
    • contextMenus
  • Types:
    • ContextType
      • all
      • page
      • frame
      • selection
      • link
      • editable
      • image
      • video
      • audio
      • launcher
      • action
    • ItemType
      • normal
      • checkbox
      • radio
      • separator
    • OnClickData
      • checked
      • editable
      • frameId
      • frameUrl
      • linkUrl
      • mediaType
      • menuItemId
      • pageUrl
      • parentMenuItemId
      • selectionText
      • srcUrl
      • wasChecked
    • Properties
      • ACTION_MENU_TOP_LEVEL_LIMIT – “The maximum number of top level extension items that can be added to an extension action context menu. Any items beyond this limit will be ignored.” Limit: 6.
    • Methods
      • create – “Creates a new context menu item.”
      • remove
      • removeAll
      • update
    • Events
      • onClicked

declarativeContent API

Are you still reading this?

  • “Use the…API to take actions depending on the content of a page, without requiring permission to read the page’s contents.”
  • Permissions:
    • declarativeContent

downloads API

Go read the official docs already.

  • Permissions:
    • downloads
  • Types
    • DownloadDelta
      • canResume
      • danger
      • endTime
      • error
      • exists
      • fileSize
      • filename
      • finalUrl – “The absolute URL that this download is being made from, after all redirects.”
      • id
      • mime
      • paused
      • startTime
      • state
      • totalBytes
      • url
    • DownloadItem
      • byExtensionId – “The identifier for the extension that initiated this download if…initiated by an extension.”
      • byExtensionName
    • FilenameConflictAction
    • FilenameSuggestion
    • DownloadOptions
      • body
      • conflictAction – “The action to take if filename already exists.”
      • filename
      • headers
      • method
      • saveAs – “Use a file-chooser to allow the suer to select a filename regardless of whether filename is set or already exists.”
      • url
    • DownloadQuery
  • Methods
    • acceptDanger
    • cancel
    • download
    • erase – “Erase matching DownloadItem from history without deleting the downloaded file.”
    • getFileIcon
    • open – “Open the downloaded file now if the DownloadItem is complete; otherwise return an error”
    • pause
    • removeFile
    • resume
    • search
    • setUiOptions – “Change the download UI of every window associated with the current browser profile.”
    • show – “Show the downloaded file in its folder in a file manager.”
    • showDefaultFolder – “Show the default Downloads folder in a file manager.”
  • Events
    • onChanged
    • onCreated
    • onDeterminingFilename – “During the filename determination process, extensions will be given the opportunity to override the target DownloadItem.filename.”
    • onErased

Events API

Howdy

  • Types
    • Event
      • addListener
      • addRules
      • getRules
      • haslistener
      • hasListeners
      • removeListener
      • removeRules
    • Rule
      • actions – “List of actions that are triggered if one of the conditions is fulfilled.”
      • conditions
      • id
      • priority
      • tags
    • UrlFilter
      • hostContains
      • hostEquals
      • hostPrefix
      • hostSuffix
      • originAndPathMatches
      • pathContains
      • pathEquals
      • pathPrefix
      • pathSuffix
      • ports
      • queryContains
      • queryEquals
      • schemes – “Matches if the scheme of the URL is equal to any of the schemes specified in the array.”
        • What is a scheme?
      • urlContains
      • urlEquals
      • urlMatches

Extension API

Hola

  • Types
    • ViewType
      • tab
      • popup
  • Methods
    • getBackgroundPage – “Returns the JavaScript ‘window’ object for the background page running inside the current extension.”
    • getViews – “Returns an array of the JaavScript ‘window’ objects for each of the pages running inside the current extension.”
    • isAllowedFileSchemeAccess
    • isAllowedIncognitoAccess
  • Events
    • None

History API

??

  • Permissions:
    • history
  • Types
    • HistoryItem – “An object encapsulating one result of a history query.”
      • id
      • lastVisitTime
      • title
      • typedCount
      • url
      • visitCount
    • UrlDetails
      • url
    • VisitItem – “An object encapsulating one visit to a URL.”
      • id
      • isLocal
      • referringVisitId
      • visitId
      • visitTime
  • Methods
    • addUrl
    • deleteAll
    • deleteRange – “Removes all items within the specified date range”
    • deleteUrl – “Removes all occurrences of the given URL”
    • getVisits – “Retrieves information about visits to a URL.”
    • search – “Searches the history for the last visit time of each page matching the query.”
  • Events
    • onVisited – “Fired when a URL is visited, providing the HistoryItem data for that URL. This event fires before the page has loaded.”
    • onVisitRemoved

Identity API

Are you playing games with me?

  • Permissions:
    • identity
  • Types
    • Account Info
      • id
    • AccountStatus
    • GetAuthTokenResult
    • InvalidTokenDetails
    • ProfileDetails
    • ProfileUserInfo
      • email
      • id
    • TokenDetails
      • account
      • enableGranularPermissions
      • interactive
      • scopes
    • WebAuthFlowDetails
  • Methods
    • clearAllCachedAuthTokens
    • getAccounts (dev channel)
    • getAuthToken
    • getProfileUserInfo
    • getRedirectURL
    • launchWebAuthFlow
    • removeCachedAuthToken
  • Events
    • onSignInChanged

Management API

Just making my way…

  • Permissions:
    • management
  • Types:
    • ExtensionInfo
      • description
      • disabledReason
      • enabled
      • homepageUrl
      • hostPermissions
      • id
      • mayDisable
      • mayEnable
      • name
      • offlineEnabled
      • optionsUrl
      • permissions
      • shortName
      • type
      • updateUrl
      • version
      • versionName
    • ExtensionInstallType
    • ExtensionType
    • LaunchType
    • UninstallOptions
  • Methods
    • generateAppForLink
    • get – “Returns information about the installed extension, app, or theme that has the given ID.”
    • getAll
    • getPermissionWarningsById
    • getPermissionWarningsByManifest
    • getSelf
    • setEnabled
      • id
      • enabled
      • callback
    • uninstall
    • uninstallSelf
  • Events
    • onDisabled
    • onEnabled
    • onInstalled
    • onUninstalled

Omnibox API

Permissions API

Runtime API

Scripting API

Sessions API

sidePanel API

Storage API

tabGroups API

webNavigation API

Something goes here.

  • Permissions:
    • webNavigation
  • Methods
    • getAllFrames
    • getFrame
  • Events
    • onBeforeNavigate – “Fired when a navigation is about to occur.”
    • onCommited – “Fired when a navigation is committed. The document…might still be downloading, but at least part of the document has been received from the server…”
    • onCompleted
    • onCreatedNavigationTarget – “Fired when a new window, or a new tab in an existing window, is created to host a navigation..”
    • onDOMContentLoaded
    • onErrorOccurred
    • onHistoryStateUpdated
    • onReferenceFragmentUpdated
    • onTabReplaced – ‘Fired when the contents of the tab is replaced by a different (usually previously pre-rendered) tab.

webRequest API

Windows API