chrome.contentSettings

Description
Use the chrome.contentSettings API to change settings that control whether websites can use features such as cookies, JavaScript, and plugins. More generally speaking, content settings allow you to customize Chrome's behavior on a per-site basis instead of globally.
Permissions
contentSettings

Manifest #

You must declare the "contentSettings" permission in your extension's manifest to use the API. For example:

{
  "name": "My extension",
  ...
  "permissions": [
    "contentSettings"
  ],
  ...
}

Content setting patterns #

You can use patterns to specify the websites that each content setting affects. For example, http://*.youtube.com/* specifies youtube.com and all of its subdomains. The syntax for content setting patterns is the same as for match patterns, with a few differences:

For http, https, and ftp URLs, the path must be a wildcard (/*). For file URLs, the path must be completely specified and must not contain wildcards.
In contrast to match patterns, content setting patterns can specify a port number. If a port number is specified, the pattern only matches websites with that port. If no port number is specified, the pattern matches all ports.

Pattern precedence #

When more than one content setting rule applies for a given site, the rule with the more specific pattern takes precedence.

For example, the following patterns are ordered by precedence:

http://www.example.com/*
http://*.example.com/* (matching example.com and all subdomains)
<all_urls> (matching every URL)

Three kinds of wildcards affect how specific a pattern is:

Wildcards in the port (for example http://www.example.com:*/*)
Wildcards in the scheme (for example *://www.example.com:123/*)
Wildcards in the hostname (for example http://*.example.com:123/*)

If a pattern is more specific than another pattern in one part but less specific in another part, the different parts are checked in the following order: hostname, scheme, port. For example, the following patterns are ordered by precedence:

http://www.example.com:*/* Specifies the hostname and scheme.
*:/www.example.com:123/* Not as high, because although it specifies the hostname, it doesn't specify the scheme.
http://*.example.com:123/* Lower because although it specifies the port and scheme, it has a wildcard in the hostname.

Primary and secondary patterns #

The URL taken into account when deciding which content setting to apply depends on the content type. For example, for contentSettings.notifications settings are based on the URL shown in the omnibox. This URL is called the "primary" URL.

Some content types can take additional URLs into account. For example, whether a site is allowed to set a contentSettings.cookies is decided based on the URL of the HTTP request (which is the primary URL in this case) as well as the URL shown in the omnibox (which is called the "secondary" URL).

If multiple rules have primary and secondary patterns, the rule with the more specific primary pattern takes precedence. If there multiple rules have the same primary pattern, the rule with the more specific secondary pattern takes precedence. For example, the following list of primary/secondary pattern pairs is ordered by precedence:

Precedence	Primary pattern	Secondary pattern
1	`http://www.moose.com/*`,	`http://www.wombat.com/*`
2	`http://www.moose.com/*`,	`<all_urls>`
3	`<all_urls>`,	`http://www.wombat.com/*`
4	`<all_urls>`,	`<all_urls>`

Resource identifiers #

Resource identifiers allow you to specify content settings for specific subtypes of a content type. Currently, the only content type that supports resource identifiers is contentSettings.plugins, where a resource identifier identifies a specific plugin. When applying content settings, first the settings for the specific plugin are checked. If there are no settings found for the specific plugin, the general content settings for plugins are checked.

For example, if a content setting rule has the resource identifier adobe-flash-player and the pattern <all_urls>, it takes precedence over a rule without a resource identifier and the pattern http://www.example.com/*, even if that pattern is more specific.

You can get a list of resource identifiers for a content type by calling the contentSettings.ContentSetting.getResourceIdentifiers method. The returned list can change with the set of installed plugins on the user's machine, but Chrome tries to keep the identifiers stable across plugin updates.

Examples #

You can find samples of this API on the sample page.

Summary

Types

ContentSetting

Properties

clear
function
Clear all content setting rules set by this extension.
The clear function looks like this:
clear(details: object, callback: function) => {...}
- details
  object
  scope
  Scope optional
  Where to clear the setting (default: regular).
- callback
  function
  The callback parameter should be a function that looks like this:
  () => {...}
get
function
Gets the current content setting for a given pair of URLs.
The get function looks like this:
get(details: object, callback: function) => {...}
- details
  object
  incognito
  boolean optional
  Whether to check the content settings for an incognito session. (default false)
  primaryUrl
  string
  The primary URL for which the content setting should be retrieved. Note that the meaning of a primary URL depends on the content type.
  resourceIdentifier
  ResourceIdentifier optional
  A more specific identifier of the type of content for which the settings should be retrieved.
  secondaryUrl
  string optional
  The secondary URL for which the content setting should be retrieved. Defaults to the primary URL. Note that the meaning of a secondary URL depends on the content type, and not all content types use secondary URLs.
- callback
  function
  The callback parameter should be a function that looks like this:
  (details: object) => {...}
  details
  object
  setting
  T
  The content setting. See the description of the individual ContentSetting objects for the possible values.
getResourceIdentifiers
function
The getResourceIdentifiers function looks like this:
getResourceIdentifiers(callback: function) => {...}
- callback
  function
  The callback parameter should be a function that looks like this:
  (resourceIdentifiers: ResourceIdentifier[]) => {...}
  resourceIdentifiers
  ResourceIdentifier[]
  A list of resource identifiers for this content type, or undefined if this content type does not use resource identifiers.
set
function
Applies a new content setting rule.
The set function looks like this:
set(details: object, callback: function) => {...}
- details
  object
  primaryPattern
  string
  The pattern for the primary URL. For details on the format of a pattern, see Content Setting Patterns.
  resourceIdentifier
  ResourceIdentifier optional
  The resource identifier for the content type.
  scope
  Scope optional
  Where to set the setting (default: regular).
  secondaryPattern
  string optional
  The pattern for the secondary URL. Defaults to matching all URLs. For details on the format of a pattern, see Content Setting Patterns.
  setting
  T
  The setting applied by this rule. See the description of the individual ContentSetting objects for the possible values.
- callback
  function
  The callback parameter should be a function that looks like this:
  () => {...}

ResourceIdentifier

The only content type using resource identifiers is plugins. For more information, see Resource Identifiers.

Properties

description
string optional
A human readable description of the resource.
id
string
The resource identifier for the given content type.

CameraContentSetting

Since Chrome 46.

Enum

"allow", "block", or "ask"

CookiesContentSetting

Since Chrome 44.

Enum

"allow", "block", or "session_only"

FullscreenContentSetting

Since Chrome 44.

Enum

"allow"

ImagesContentSetting

Since Chrome 44.

Enum

"allow", or "block"

JavascriptContentSetting

Since Chrome 44.

Enum

"allow", or "block"

LocationContentSetting

Since Chrome 44.

Enum

"allow", "block", or "ask"

MicrophoneContentSetting

Since Chrome 46.

Enum

"allow", "block", or "ask"

MouselockContentSetting

Since Chrome 44.

Enum

"allow"

MultipleAutomaticDownloadsContentSetting

Since Chrome 44.

Enum

"allow", "block", or "ask"

NotificationsContentSetting

Since Chrome 44.

Enum

"allow", "block", or "ask"

PluginsContentSetting

Since Chrome 44.

Enum

"allow", "block", or "detect_important_content"

PopupsContentSetting

Since Chrome 44.

Enum

"allow", or "block"

PpapiBrokerContentSetting

Since Chrome 44.

Enum

"allow", "block", or "ask"

Scope

Since Chrome 44.

The scope of the ContentSetting. One of
regular: setting for regular profile (which is inherited by the incognito profile if not overridden elsewhere),
incognito_session_only: setting for incognito profile that can only be set during an incognito session and is deleted when the incognito session ends (overrides regular settings).

Enum

"regular", or "incognito_session_only"

Properties

automaticDownloads

Since Chrome 42.

Whether to allow sites to download multiple files automatically. One of
allow: Allow sites to download multiple files automatically,
block: Don't allow sites to download multiple files automatically,
ask: Ask when a site wants to download files automatically after the first file.
Default is ask.
The primary URL is the URL of the top-level frame. The secondary URL is not used.

Type

ContentSetting<MultipleAutomaticDownloadsContentSetting>

camera

Since Chrome 46.

Whether to allow sites to access the camera. One of
allow: Allow sites to access the camera,
block: Don't allow sites to access the camera,
ask: Ask when a site wants to access the camera.
Default is ask.
The primary URL is the URL of the document which requested camera access. The secondary URL is not used.
NOTE: The 'allow' setting is not valid if both patterns are '<all_urls>'.

Type

ContentSetting<CameraContentSetting>

cookies

Whether to allow cookies and other local data to be set by websites. One of
allow: Accept cookies,
block: Block cookies,
session_only: Accept cookies only for the current session.
Default is allow.
The primary URL is the URL representing the cookie origin. The secondary URL is the URL of the top-level frame.

Type

ContentSetting<CookiesContentSetting>

fullscreen

Since Chrome 42.

Deprecated. No longer has any effect. Fullscreen permission is now automatically granted for all sites. Value is always allow.

Type

ContentSetting<FullscreenContentSetting>

images

Whether to show images. One of
allow: Show images,
block: Don't show images.
Default is allow.
The primary URL is the URL of the top-level frame. The secondary URL is the URL of the image.

Type

ContentSetting<ImagesContentSetting>

javascript

Whether to run JavaScript. One of
allow: Run JavaScript,
block: Don't run JavaScript.
Default is allow.
The primary URL is the URL of the top-level frame. The secondary URL is not used.

Type

ContentSetting<JavascriptContentSetting>

location

Since Chrome 42.

Whether to allow Geolocation. One of
allow: Allow sites to track your physical location,
block: Don't allow sites to track your physical location,
ask: Ask before allowing sites to track your physical location.
Default is ask.
The primary URL is the URL of the document which requested location data. The secondary URL is the URL of the top-level frame (which may or may not differ from the requesting URL).

Type

ContentSetting<LocationContentSetting>

microphone

Since Chrome 46.

Whether to allow sites to access the microphone. One of
allow: Allow sites to access the microphone,
block: Don't allow sites to access the microphone,
ask: Ask when a site wants to access the microphone.
Default is ask.
The primary URL is the URL of the document which requested microphone access. The secondary URL is not used.
NOTE: The 'allow' setting is not valid if both patterns are '<all_urls>'.

Type

ContentSetting<MicrophoneContentSetting>

mouselock

Since Chrome 42.

Deprecated. No longer has any effect. Mouse lock permission is now automatically granted for all sites. Value is always allow.

Type

ContentSetting<MouselockContentSetting>

notifications

Whether to allow sites to show desktop notifications. One of
allow: Allow sites to show desktop notifications,
block: Don't allow sites to show desktop notifications,
ask: Ask when a site wants to show desktop notifications.
Default is ask.
The primary URL is the URL of the document which wants to show the notification. The secondary URL is not used.

Type

ContentSetting<NotificationsContentSetting>

plugins

Whether to run plugins. One of
allow: Run plugins automatically,
block: Don't run plugins automatically,
detect_important_content: Only run automatically those plugins that are detected as the website's main content.
The primary URL is the URL of the top-level frame. The secondary URL is not used.

Type

ContentSetting<PluginsContentSetting>

popups

Whether to allow sites to show pop-ups. One of
allow: Allow sites to show pop-ups,
block: Don't allow sites to show pop-ups.
Default is block.
The primary URL is the URL of the top-level frame. The secondary URL is not used.

Type

ContentSetting<PopupsContentSetting>

unsandboxedPlugins

Since Chrome 42.

Whether to allow sites to run plugins unsandboxed. One of
allow: Allow sites to run plugins unsandboxed,
block: Don't allow sites to run plugins unsandboxed,
ask: Ask when a site wants to run a plugin unsandboxed.
Default is ask.
The primary URL is the URL of the top-level frame. The secondary URL is not used.

Type

ContentSetting<PpapiBrokerContentSetting>