Google Chrome Extensions

chrome.contentSettings

The content settings module allows you to change settings that control whether websites can use features such as cookies, JavaScript, and plug-ins. More generally speaking, content settings allow you to customize Chrome's behavior on a per-site basis instead of globally.

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:

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:

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

Three kinds of wildcards affect how specific a pattern is:

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:

  1. http://www.example.com:*/*
    Specifies the hostname and scheme.
  2. *:/www.example.com:123/*
    Not as high, because although it specifies the hostname, it doesn't specify the scheme.
  3. 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 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 cookie 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:

PrecedencePrimary patternSecondary 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 plugins, where a resource identifier identifies a specific plug-in. When applying content settings, first the settings for the specific plug-in are checked. If there are no settings found for the specific plug-in, the general content settings for plug-ins 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 getResourceIdentifiers() method. The returned list can change with the set of installed plug-ins on the user's machine, but Chrome tries to keep the identifiers stable across plug-in updates.

Examples

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

API Reference: chrome.contentSettings

Types

ResourceIdentifier

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

Properties of ResourceIdentifier

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

ContentSetting

( object )

Methods of ContentSetting

clear

ContentSetting.clear(object details)

Clear all content setting rules set by this extension.

Parameters

details ( object )
scope ( optional enumerated string ["regular", "incognito_session_only"] )
Where to set the setting (default: regular). 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).

Callback function

If you specify the callback parameter, it should specify a function that looks like this:

function() {...};

get

ContentSetting.get(object details)

Gets the current content setting for a given pair of URLs.

Parameters

details ( object )
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.
secondaryUrl ( optional string )
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.
resourceIdentifier ( optional ResourceIdentifier )
A more specific identifier of the type of content for which the settings should be retrieved.
incognito ( optional boolean )
Whether to check the content settings for an incognito session. (default false)

Callback function

The callback parameter should specify a function that looks like this:

function(object details) {...};
details ( object )
setting ( any )
The content setting. See the description of the individual ContentSetting objects for the possible values.

set

ContentSetting.set(object details)

Applies a new content setting rule.

Parameters

details ( object )
primaryPattern ( string )
The pattern for the primary URL. For details on the format of a pattern, see Content Setting Patterns.
secondaryPattern ( optional string )
The pattern for the secondary URL. Defaults to matching all URLs. For details on the format of a pattern, see Content Setting Patterns.
resourceIdentifier ( optional ResourceIdentifier )
The resource identifier for the content type.
setting ( any )
The setting applied by this rule. See the description of the individual ContentSetting objects for the possible values.
scope ( optional enumerated string ["regular", "incognito_session_only"] )
Where to clear the setting (default: regular). 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).

Callback function

If you specify the callback parameter, it should specify a function that looks like this:

function() {...};

getResourceIdentifiers

ContentSetting.getResourceIdentifiers()

Properties

cookies

chrome.contentSettings.cookies
cookies ( ContentSetting )
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.

images

chrome.contentSettings.images
images ( ContentSetting )
Whether to show images. One of
allow: Show images,
block: Don't show images.
Default is allow.
The primary URL is the main-frame URL. The secondary URL is the URL of the image.

javascript

chrome.contentSettings.javascript
javascript ( ContentSetting )
Whether to run JavaScript. One of
allow: Run JavaScript,
block: Don't run JavaScript.
Default is allow.
The primary URL is the main-frame URL. The secondary URL is not used.

plugins

chrome.contentSettings.plugins
plugins ( ContentSetting )
Whether to run plug-ins. One of
allow: Run plug-ins automatically,
block: Don't run plug-ins automatically.
Default is allow.
The primary URL is the main-frame URL. The secondary URL is not used.

popups

chrome.contentSettings.popups
popups ( ContentSetting )
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 main-frame URL. The secondary URL is not used.

notifications

chrome.contentSettings.notifications
notifications ( ContentSetting )
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 main-frame URL. The secondary URL is not used.

Sample Extensions that use chrome.contentSettings

  • Per-plugin content settings – Customize your content setting for different plug-ins.