Overriding Chrome settings

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

Home page, search provider, and startup pages

Here is an example how home page, search provider and startup pages can be modified in the extension manifest. Web sites used in the settings API must be verified (via Webmaster Tools) as being associated with that item in the Chrome Web Store. Note that if you verify ownership for a domain (for example, http://example.com) you can use any subdomain or page (for example, http://app.example.com or http://example.com/page.html) within your extension.

{
  "name": "My extension",
  ...
  "chrome_settings_overrides": {
    "homepage": "http://www.homepage.com",
    "search_provider": {
        "name": "name.__MSG_url_domain__",
        "keyword": "keyword.__MSG_url_domain__",
        "search_url": "http://www.foo.__MSG_url_domain__/s?q={searchTerms}",
        "favicon_url": "http://www.foo.__MSG_url_domain__/favicon.ico",
        "suggest_url": "http://www.foo.__MSG_url_domain__/suggest?q={searchTerms}",
        "instant_url": "http://www.foo.__MSG_url_domain__/instant?q={searchTerms}",
        "image_url": "http://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": [
          "http://www.moo.__MSG_url_domain__/s?q={searchTerms}",
          "http://www.noo.__MSG_url_domain__/s?q={searchTerms}"
        ],
        "encoding": "UTF-8",
        "is_default": true
    },
    "startup_pages": ["http://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. A new registry entry should be created next to the "update_url" key (see instructions here). The value name is "install_parameter", the value data 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

  Type	Attribute	Description
  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.
  string	search_url	An 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.
  boolean	is_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.