欢迎 What's new in Chrome extensions Get help with Chrome extensions API reference Samples
欢迎 What's new in Chrome extensions Get help with Chrome extensions API reference Samples

Overriding Chrome settings

Published on Updated on

Settings overrides are a way for extensions to override selected Chrome settings. The API is available on Windows and Mac in all current versions of Chrome.

Homepage, search provider, and startup pages

Here is an example of how homepage, search provider, and startup pages can be modified in the extension manifest. Any domain used in the settings API must be verified (via Google Search Console) by the same developer account publishing the extension. Note that if you verify ownership for a domain (for example, https://example.com) you can use any subdomain or page (for example, https://app.example.com or https://example.com/page.html) within your extension.

Using the settings override permission while also requesting any additional capabilities or permissions is inconsistent with our single purpose policy. When Chrome detects that an item is potentially violating our single purpose policy, a confirmation dialog is shown to the user. Extensions that limit themselves to only modifying a single setting without seeking additional capabilities or permissions do not get a confirmation dialog.

This applies to Chrome 107 and later.

{
"name": "My extension",
...
"chrome_settings_overrides": {
"homepage": "https://www.homepage.com",
"search_provider": {
"name": "name.__MSG_url_domain__",
"keyword": "keyword.__MSG_url_domain__",
"search_url": "https://www.foo.__MSG_url_domain__/s?q={searchTerms}",
"favicon_url": "https://www.foo.__MSG_url_domain__/favicon.ico",
"suggest_url": "https://www.foo.__MSG_url_domain__/suggest?q={searchTerms}",
"instant_url": "https://www.foo.__MSG_url_domain__/instant?q={searchTerms}",
"image_url": "https://www.foo.__MSG_url_domain__/image?q={searchTerms}",
"search_url_post_params": "search_lang=__MSG_url_domain__",
"suggest_url_post_params": "suggest_lang=__MSG_url_domain__",
"instant_url_post_params": "instant_lang=__MSG_url_domain__",
"image_url_post_params": "image_lang=__MSG_url_domain__",
"alternate_urls": [
"https://www.moo.__MSG_url_domain__/s?q={searchTerms}",
"https://www.noo.__MSG_url_domain__/s?q={searchTerms}"
],
"encoding": "UTF-8",
"is_default": true
},
"startup_pages": ["https://www.startup.com"]
},
"default_locale": "de",
...
}

Customizing values

Values in the manifest can be customized in the following ways:

  • All values of the search_provider, homepage, and startup_pages properties can be localized using the chrome.i18n API.

  • For external extensions, the search_provider, homepage and startup_pages URL values can be parametrized using a registry key. Create a new registry entry next to the "update_url" key (see instructions here). The key name is "install_parameter", the value is an arbitrary string:

    {
    "update_url": "https://clients2.google.com/service/update2/crx",
    "install_parameter": "Value"
    }

    All occurrences of the substring "__PARAM__" in the manifest URLs will be substituted with the "install_parameter" value. If "install_parameter" is absent, occurrences of "__PARAM__" are removed. Note that "__PARAM__" cannot be part of the hostname. It needs to occur after the first '/' in the URL.

Reference

An extension can override one or more of the following properties in the manifest:

  • homepage (string) - optional

    New value for the homepage.

  • search_provider (object) - optional

    A search engine

    TypeAttributeDescription
    string(optional) name

    Name of the search engine displayed to user. This may only be omitted if prepopulated_id is set.

    string(optional) keyword

    Omnibox keyword for the search engine. This may only be omitted if prepopulated_id is set.

    string(optional) favicon_url

    An icon URL for the search engine. This may only be omitted if prepopulated_id is set.

    stringsearch_url

    A search URL used by the search engine.

    string(optional) encoding

    Encoding of the search term. This may only be omitted if prepopulated_id is set.

    string(optional) suggest_url

    If omitted, this engine does not support suggestions.

    string(optional) image_url

    If omitted, this engine does not support image search.

    string(optional) search_url_post_params

    The string of post parameters to search_url

    string(optional) suggest_url_post_params

    The string of post parameters to suggest_url

    string(optional) image_url_post_params

    The string of post parameters to image_url

    array of string(optional) alternate_urls

    A list of URL patterns that can be used, in addition to search_url.

    integer(optional) prepopulated_id

    An ID of the built-in search engine in Chrome.

    booleanis_default

    Specifies if the search provider should be default.

  • startup_pages (array of string) - optional

An array of length one containing a URL to be used as the startup page.

Updated on Improve article

We serve cookies on this site to analyze traffic, remember your preferences, and optimize your experience.