Google Chrome Extensions

chrome.types

The chrome.types module contains type declarations for Chrome. Currently this comprises only a prototype for giving other modules access to manage Chrome browser settings. This prototype is used, for example, for chrome.proxy.settings.

Chrome settings

The ChromeSetting prototype provides a common set of functions (get(), set(), and clear()) as well as an event publisher (onChange) for settings of the Chrome browser. The proxy settings examples demonstrate how these functions are intended to be used.

Scope and life cycle

Chrome distinguishes between three different scopes of browser settings:

regular
Settings set in the regular scope apply to regular browser windows and are inherited by incognito windows if they are not overwritten. These settings are stored to disk and remain in place until they are cleared by the governing extension, or the governing extension is disabled or uninstalled.
incognito_persistent
Settings set in the incognito_persistent scope apply only to incognito windows. For these, they override regular settings. These settings are stored to disk and remain in place until they are cleared by the governing extension, or the governing extension is disabled or uninstalled.
incognito_session_only
Settings set in the incognito_session_only scope apply only to incognito windows. For these, they override regular and incognito_session_only settings. These settings are not stored to disk and are cleared when the last incognito window is closed. They can only be set when at least one incognito window is open.

Precedence

Chrome manages settings on different layers. The following list describes the layers that may influence the effective settings, in increasing order of precedence.

  1. System settings provided by the operating system
  2. Command-line parameters
  3. Settings provided by extensions
  4. Policies

As the list implies, policies might overrule any changes that you specify with your extension. You can use the get() function to determine whether your extension is capable of providing a setting or whether this setting would be overridden.

As discussed above, Chrome allows using different settings for regular windows and incognito windows. The following example illustrates the behavior. Assume that no policy overrides the settings and that an extension can set settings for regular windows (R) and settings for incognito windows (I).

If two or more extensions want to set the same setting to different values, the extension installed most recently takes precedence over the other extensions. If the most recently installed extension sets only (I), the settings of regular windows can be defined by previously installed extensions.

The effective value of a setting is the one that results from considering the precedence rules. It is used by Chrome.

API Reference: chrome.types

Types

ChromeSetting

( object )
An interface which allows access to a Chrome browser setting.

Methods of ChromeSetting

get

ChromeSetting.get(object details)

Gets the value of a setting.

Parameters

details ( object )
What setting to consider.
incognito ( optional boolean )
Whether to return the setting that applies to the incognito session (default false).

Callback function

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

function(object details) {...};
details ( object )
Details of the currently effective value.
value ( any )
The value of the setting.
levelOfControl ( enumerated string ["not_controllable", "controlled_by_other_extensions", "controllable_by_this_extension", "controlled_by_this_extension"] )
One of
not_controllable: cannot be controlled by any extension
controlled_by_other_extensions: controlled by extensions with higher precedence
controllable_by_this_extension: can be controlled by this extension
controlled_by_this_extension: controlled by this extension
incognitoSpecific ( optional boolean )
Whether the effective value is specific to the incognito session.
This property will only be present if the incognito property in the details parameter of get() was true.

set

ChromeSetting.set(object details)

Sets the value of a setting.

Parameters

details ( object )
What setting to change.
value ( any )
The value of the setting.
Note that every setting has a specific value type, which is described together with the setting. An extension should not set a value of a different type.
scope ( optional enumerated string ["regular", "regular_only", "incognito_persistent", "incognito_session_only"] )
Where to set the setting (default: regular). One of
regular: setting for the regular profile (which is inherited by the incognito profile if not overridden elsewhere),
regular_only: setting for the regular profile only (not inherited by the incognito profile),
incognito_persistent: setting for the incognito profile that survives browser restarts (overrides regular preferences),
incognito_session_only: setting for the incognito profile that can only be set during an incognito session and is deleted when the incognito session ends (overrides regular and incognito_persistent preferences).

Callback function

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

function() {...};

clear

ChromeSetting.clear(object details)

Clears the setting. This way default settings can become effective again.

Parameters

details ( object )
What setting to clear.
scope ( optional enumerated string ["regular", "regular_only", "incognito_persistent", "incognito_session_only"] )
Where to clear the setting (default: regular). One of
regular: setting for the regular profile (which is inherited by the incognito profile if not overridden elsewhere),
regular_only: setting for the regular profile only (not inherited by the incognito profile),
incognito_persistent: setting for the incognito profile that survives browser restarts (overrides regular preferences),
incognito_session_only: setting for the incognito profile that can only be set during an incognito session and is deleted when the incognito session ends (overrides regular and incognito_persistent preferences).

Callback function

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

function() {...};

Events of ChromeSetting

onChange

ChromeSetting.onChange.addListener(function(object details) {...});

Fired when the value of the setting changes.

Listener Parameters

details ( object )
value ( any )
The value of the setting.
levelOfControl ( enumerated string ["not_controllable", "controlled_by_other_extensions", "controllable_by_this_extension", "controlled_by_this_extension"] )
One of
not_controllable: cannot be controlled by any extension
controlled_by_other_extensions: controlled by extensions with higher precedence
controllable_by_this_extension: can be controlled by this extension
controlled_by_this_extension: controlled by this extension
incognitoSpecific ( optional boolean )
Whether the value that has changed is specific to the incognito session.
This property will only be present if the user has enabled the extension in incognito mode.