whale.management
| Description: | The whale.management API provides ways to manage the list of extensions/apps that are installed and running. It is particularly useful for extensions that override the built-in New Tab page. |
|---|---|
| Availability: | Since Chrome 20. |
| Permissions: | "management" |
{
"name": "My extension",
...
**"permissions": [
"management"
]**,
...
}
[management.getPermissionWarningsByManifest](/extensions/management#method-getPermissionWarningsByManifest), [management.uninstallSelf](/extensions/management#method-uninstallSelf), and [management.getSelf](/extensions/management#method-getSelf) do not require the management permission.
## Types
### IconInfo
Information about an icon belonging to an extension, app, or theme.
| properties |
|---|
| integer | size |
A number representing the width and height of the icon. Likely values include (but are not limited to) 128, 48, 24, and 16.
|
| string | url |
The URL for this icon image. To display a grayscale version of the icon (to indicate that an extension is disabled, for example), append `?grayscale=true` to the URL.
|
### LaunchType
These are all possible app launch types.
| Enum |
|---|
| `"OPEN_AS_REGULAR_TAB"`, `"OPEN_AS_PINNED_TAB"`, `"OPEN_AS_WINDOW"`, or `"OPEN_FULL_SCREEN"` |
### ExtensionDisabledReason
A reason the item is disabled.
| Enum |
|---|
| `"unknown"`, or `"permissions_increase"` |
### ExtensionType
The type of this extension, app, or theme.
| Enum |
|---|
| `"extension"`, `"hosted_app"`, `"packaged_app"`, `"legacy_packaged_app"`, or `"theme"` |
### ExtensionInstallType
How the extension was installed. One of
admin: The extension was installed because of an administrative policy,
development: The extension was loaded unpacked in developer mode,
normal: The extension was installed normally via a .crx file,
sideload: The extension was installed by other software on the machine,
other: The extension was installed by other means.
| Enum |
|---|
| `"admin"`, `"development"`, `"normal"`, `"sideload"`, or `"other"` |
### ExtensionInfo
Information about an installed extension, app, or theme.
| properties |
|---|
| string | id |
The extension's unique identifier.
|
| string | name |
The name of this extension, app, or theme.
|
| string | shortName |
Since Chrome 31.
A short version of the name of this extension, app, or theme.
|
| string | description |
The description of this extension, app, or theme.
|
| string | version |
The [version](manifest/version) of this extension, app, or theme.
|
| string | (optional) versionName |
Since Chrome 50.
The [version name](manifest/version#version_name) of this extension, app, or theme if the manifest specified one.
|
| boolean | mayDisable |
Whether this extension can be disabled or uninstalled by the user.
|
| boolean | (optional) mayEnable |
Since Chrome 62.
Whether this extension can be enabled by the user. This is only returned for extensions which are not enabled.
|
| boolean | enabled |
Whether it is currently enabled or disabled.
|
| [ExtensionDisabledReason](/extensions/management#type-ExtensionDisabledReason) | (optional) disabledReason |
A reason the item is disabled.
|
| boolean | isApp |
**Deprecated** since Chrome 33. Please use [management.ExtensionInfo.type](/extensions/management#property-ExtensionInfo-type).
True if this is an app.
|
| [ExtensionType](/extensions/management#type-ExtensionType) | type |
Since Chrome 23.
The type of this extension, app, or theme.
|
| string | (optional) appLaunchUrl |
The launch url (only present for apps).
|
| string | (optional) homepageUrl |
The URL of the homepage of this extension, app, or theme.
|
| string | (optional) updateUrl |
The update URL of this extension, app, or theme.
|
| boolean | offlineEnabled |
Whether the extension, app, or theme declares that it supports offline.
|
| string | optionsUrl |
The url for the item's options page, if it has one.
|
| array of [IconInfo](/extensions/management#type-IconInfo) | (optional) icons |
A list of icon information. Note that this just reflects what was declared in the manifest, and the actual image at that url may be larger or smaller than what was declared, so you might consider using explicit width and height attributes on img tags referencing these images. See the [manifest documentation on icons](manifest/icons) for more details.
|
| array of string | permissions |
Returns a list of API based permissions.
|
| array of string | hostPermissions |
Returns a list of host based permissions.
|
| [ExtensionInstallType](/extensions/management#type-ExtensionInstallType) | installType |
Since Chrome 22.
How the extension was installed.
|
| [LaunchType](/extensions/management#type-LaunchType) | (optional) launchType |
Since Chrome 37.
The app launch type (only present for apps).
|
| array of [LaunchType](/extensions/management#type-LaunchType) | (optional) availableLaunchTypes |
Since Chrome 37.
The currently available launch types (only present for apps).
|
## Methods
### getAll
`whale.management.getAll(function callback)`
Returns a list of information about installed extensions and apps.
| Parameters |
|---|
| function | (optional) callback |
If you specify the _callback_ parameter, it should be a function that looks like this:
`function(array of [ExtensionInfo](/extensions/management#type-ExtensionInfo) result) {...};`
| array of [ExtensionInfo](/extensions/management#type-ExtensionInfo) | result | |
|---|---|---|
|
### get
`whale.management.get(string id, function callback)`
Returns information about the installed extension, app, or theme that has the given ID.
| Parameters |
|---|
| string | id |
The ID from an item of [management.ExtensionInfo](/extensions/management#type-ExtensionInfo).
|
| function | (optional) callback |
If you specify the _callback_ parameter, it should be a function that looks like this:
`function( [ExtensionInfo](/extensions/management#type-ExtensionInfo) result) {...};`
| [ExtensionInfo](/extensions/management#type-ExtensionInfo) | result | |
|---|---|---|
|
### getSelf
`whale.management.getSelf(function callback)`
Since Chrome 39.
Returns information about the calling extension, app, or theme. Note: This function can be used without requesting the 'management' permission in the manifest.
| Parameters |
|---|
| function | (optional) callback |
If you specify the _callback_ parameter, it should be a function that looks like this:
`function( [ExtensionInfo](/extensions/management#type-ExtensionInfo) result) {...};`
| [ExtensionInfo](/extensions/management#type-ExtensionInfo) | result | |
|---|---|---|
|
### getPermissionWarningsById
`whale.management.getPermissionWarningsById(string id, function callback)`
Returns a list of [permission warnings](permission_warnings) for the given extension id.
| Parameters |
|---|
| string | id |
The ID of an already installed extension.
|
| function | (optional) callback |
If you specify the _callback_ parameter, it should be a function that looks like this:
`function(array of string permissionWarnings) {...};`
| array of string | permissionWarnings | |
|---|---|---|
|
### getPermissionWarningsByManifest
`whale.management.getPermissionWarningsByManifest(string manifestStr, function callback)`
Returns a list of [permission warnings](permission_warnings) for the given extension manifest string. Note: This function can be used without requesting the 'management' permission in the manifest.
| Parameters |
|---|
| string | manifestStr |
Extension manifest JSON string.
|
| function | (optional) callback |
If you specify the _callback_ parameter, it should be a function that looks like this:
`function(array of string permissionWarnings) {...};`
| array of string | permissionWarnings | |
|---|---|---|
|
### setEnabled
Enables or disables an app or extension. In most cases this function must be called in the context of a user gesture (e.g. an onclick handler for a button), and may present the user with a native confirmation UI as a way of preventing abuse.
| Parameters |
|---|
| string | id |
This should be the id from an item of [management.ExtensionInfo](/extensions/management#type-ExtensionInfo).
|
| boolean | enabled |
Whether this item should be enabled or disabled.
|
| function | (optional) callback |
If you specify the _callback_ parameter, it should be a function that looks like this:
`function() {...};` |
### uninstall
Uninstalls a currently installed app or extension.
| Parameters |
|---|
| string | id |
This should be the id from an item of [management.ExtensionInfo](/extensions/management#type-ExtensionInfo).
|
| object | (optional) options |
Since Chrome 21.
| boolean | (optional) showConfirmDialog |
|---|---|
Whether or not a confirm-uninstall dialog should prompt the user. Defaults to false for self uninstalls. If an extension uninstalls another extension, this parameter is ignored and the dialog is always shown.
|
|
| function | (optional) callback |
If you specify the _callback_ parameter, it should be a function that looks like this:
`function() {...};` |
### uninstallSelf
`whale.management.uninstallSelf(object options, function callback)`
Since Chrome 26.
Uninstalls the calling extension. Note: This function can be used without requesting the 'management' permission in the manifest.
| Parameters |
|---|
| object | (optional) options |
| boolean | (optional) showConfirmDialog |
|---|---|
Whether or not a confirm-uninstall dialog should prompt the user. Defaults to false.
|
|
| function | (optional) callback |
If you specify the _callback_ parameter, it should be a function that looks like this:
`function() {...};` |
### launchApp
`whale.management.launchApp(string id, function callback)`
Launches an application.
| Parameters |
|---|
| string | id |
The extension id of the application.
|
| function | (optional) callback |
If you specify the _callback_ parameter, it should be a function that looks like this:
`function() {...};` |
### createAppShortcut
`whale.management.createAppShortcut(string id, function callback)`
Since Chrome 37.
Display options to create shortcuts for an app. On Mac, only packaged app shortcuts can be created.
| Parameters |
|---|
| string | id |
Since Chrome 36.
This should be the id from an app item of [management.ExtensionInfo](/extensions/management#type-ExtensionInfo).
|
| function | (optional) callback |
If you specify the _callback_ parameter, it should be a function that looks like this:
`function() {...};` |
### setLaunchType
`whale.management.setLaunchType(string id, [LaunchType](/extensions/management#type-LaunchType) launchType, function callback)`
Since Chrome 37.
Set the launch type of an app.
| Parameters |
|---|
| string | id |
This should be the id from an app item of [management.ExtensionInfo](/extensions/management#type-ExtensionInfo).
|
| [LaunchType](/extensions/management#type-LaunchType) | launchType |
The target launch type. Always check and make sure this launch type is in [ExtensionInfo.availableLaunchTypes](/extensions/management#property-ExtensionInfo-availableLaunchTypes), because the available launch types vary on different platforms and configurations.
|
| function | (optional) callback |
If you specify the _callback_ parameter, it should be a function that looks like this:
`function() {...};` |
### generateAppForLink
## Events
Since Chrome 37.
Generate an app for a URL. Returns the generated bookmark app.
| Parameters |
|---|
| string | url |
The URL of a web page. The scheme of the URL can only be "http" or "https".
|
| string | title |
The title of the generated app.
|
| function | (optional) callback |
If you specify the _callback_ parameter, it should be a function that looks like this:
`function( [ExtensionInfo](/extensions/management#type-ExtensionInfo) result) {...};`
| [ExtensionInfo](/extensions/management#type-ExtensionInfo) | result | |
|---|---|---|
|
### onInstalled
Fired when an app or extension has been installed.
#### addListener
`whale.management.onInstalled.addListener(function callback)`
| Parameters |
|---|
| function | callback |
The _callback_ parameter should be a function that looks like this:
`function( [ExtensionInfo](/extensions/management#type-ExtensionInfo) info) {...};`
| [ExtensionInfo](/extensions/management#type-ExtensionInfo) | info | |
|---|---|---|
|
### onUninstalled
Fired when an app or extension has been uninstalled.
#### addListener
`whale.management.onUninstalled.addListener(function callback)`
| Parameters |
|---|
| function | callback |
The _callback_ parameter should be a function that looks like this:
`function(string id) {...};`
| string | id |
|---|---|
The id of the extension, app, or theme that was uninstalled.
|
|
### onEnabled
Fired when an app or extension has been enabled.
#### addListener
`whale.management.onEnabled.addListener(function callback)`
| Parameters |
|---|
| function | callback |
The _callback_ parameter should be a function that looks like this:
`function( [ExtensionInfo](/extensions/management#type-ExtensionInfo) info) {...};`
| [ExtensionInfo](/extensions/management#type-ExtensionInfo) | info | |
|---|---|---|
|
### onDisabled
Fired when an app or extension has been disabled.
#### addListener
`whale.management.onDisabled.addListener(function callback)`
| Parameters |
|---|
| function | callback |
The _callback_ parameter should be a function that looks like this:
`function( [ExtensionInfo](/extensions/management#type-ExtensionInfo) info) {...};`
| [ExtensionInfo](/extensions/management#type-ExtensionInfo) | info | |
|---|---|---|
|