From 9e318a36e136060440b6a94797dcddd345fd472c Mon Sep 17 00:00:00 2001 From: amysteamdev <37001393+AmySteam@users.noreply.github.com> Date: Fri, 4 Nov 2022 10:24:18 -0500 Subject: [PATCH 01/17] Rewrite intro --- site/en/docs/extensions/mv3/manifest/index.md | 18 ++++++++---------- 1 file changed, 8 insertions(+), 10 deletions(-) diff --git a/site/en/docs/extensions/mv3/manifest/index.md b/site/en/docs/extensions/mv3/manifest/index.md index c88a5dc71086..1b8ef59db80c 100644 --- a/site/en/docs/extensions/mv3/manifest/index.md +++ b/site/en/docs/extensions/mv3/manifest/index.md @@ -1,20 +1,18 @@ --- -layout: "layouts/doc-post.njk" -title: "Manifest file format" +layout: 'layouts/doc-post.njk' +title: 'Manifest file format' date: 2012-09-18 -updated: 2021-10-08 -description: An overview of the manifest.json properties that you can use in your Chrome Extension. +updated: 2022-11-08 +description: An overview of the manifest.json properties of a Chrome Extension. --- -{# TODO: need to create any required child pages for new mv3 properties, e.g. host_permissions, and link them here. #} - -Every extension has a [JSON][1]\-formatted manifest file, named `manifest.json`, that provides -important information. +Every extension requires a [JSON][1]\-formatted file, named `manifest.json`, that provides +important information. This file must be located in the extension's root directory. ## Field summary {: #overview } -The following code shows the supported manifest fields for Extensions, with links to the page that -discusses each field. +The following code shows the supported manifest keys, with links to pages that +describe each property. 
{
   // Required

From 9c3fb349173fa97f7c0cdc2e46cd07f82916b5e8 Mon Sep 17 00:00:00 2001
From: amysteamdev <37001393+AmySteam@users.noreply.github.com>
Date: Fri, 4 Nov 2022 10:28:38 -0500
Subject: [PATCH 02/17] Remove keys for internal use only

---
 site/en/docs/extensions/mv3/manifest/index.md | 5 -----
 1 file changed, 5 deletions(-)

diff --git a/site/en/docs/extensions/mv3/manifest/index.md b/site/en/docs/extensions/mv3/manifest/index.md
index 1b8ef59db80c..babd3abe7f0e 100644
--- a/site/en/docs/extensions/mv3/manifest/index.md
+++ b/site/en/docs/extensions/mv3/manifest/index.md
@@ -41,13 +41,10 @@ describe each property.
   "content_capabilities": ...,
   "content_scripts": [{...}],
   "content_security_policy": {...},
-  "converted_from_user_script": ...,
   "cross_origin_embedder_policy": {"value": "require-corp"},
   "cross_origin_opener_policy": {"value": "same-origin"},
-  "current_locale": ...,
   "declarative_net_request": ...,
   "devtools_page": "devtools.html",
-  "differential_fingerprint": ...,
   "event_rules": [{...}],
   "externally_connectable": {
     "matches": ["*://*.example.com/*"]
@@ -79,7 +76,6 @@ describe each property.
     "page": "options.html"
   },
   "permissions": ["tabs"],
-  "platforms": ...,
   "replacement_web_app": ...,
   "requirements": {...},
   "sandbox": [...],
@@ -87,7 +83,6 @@ describe each property.
   "storage": {
     "managed_schema": "schema.json"
   },
-  "system_indicator": ...,
   "tts_engine": {...},
   "update_url": "https://path/to/updateInfo.xml",
   "version_name": "aString",

From 68eafe544f6bf852b120f204e8657bd6d750b409 Mon Sep 17 00:00:00 2001
From: amysteamdev <37001393+AmySteam@users.noreply.github.com>
Date: Fri, 4 Nov 2022 10:39:24 -0500
Subject: [PATCH 03/17] Add mdn json link

---
 site/en/docs/extensions/mv3/manifest/index.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/site/en/docs/extensions/mv3/manifest/index.md b/site/en/docs/extensions/mv3/manifest/index.md
index babd3abe7f0e..3ede26ca9c56 100644
--- a/site/en/docs/extensions/mv3/manifest/index.md
+++ b/site/en/docs/extensions/mv3/manifest/index.md
@@ -6,7 +6,7 @@ updated: 2022-11-08
 description: An overview of the manifest.json properties of a Chrome Extension.
 ---
 
-Every extension requires a [JSON][1]\-formatted file, named `manifest.json`, that provides
+Every extension requires a [JSON][mdn-json]\-formatted file, named `manifest.json`, that provides
 important information. This file must be located in the extension's root directory.
 
 ## Field summary {: #overview }
@@ -89,4 +89,4 @@ describe each property.
   "web_accessible_resources": [...]
 }
-[1]: https://www.json.org +[mdn-json]: https://developer.mozilla.org/docs/Glossary/JSON From f9d2e553637f01cf203bb0e1145b86d99cf5f0bd Mon Sep 17 00:00:00 2001 From: amysteamdev <37001393+AmySteam@users.noreply.github.com> Date: Tue, 8 Nov 2022 13:12:32 -0600 Subject: [PATCH 04/17] Add code samples Minor tweaks --- .../mv3/manifest/default_locale/index.md | 13 ++- .../mv3/manifest/description/index.md | 16 +++- .../manifest/externally_connectable/index.md | 80 ++++++---------- .../extensions/mv3/manifest/icons/index.md | 3 +- .../mv3/manifest/manifest_version/index.md | 8 +- .../extensions/mv3/manifest/name/index.md | 24 +++-- .../extensions/mv3/manifest/version/index.md | 20 ++-- .../extensions/mv3/shared_modules/index.md | 95 +++++++++++++++++++ 8 files changed, 173 insertions(+), 86 deletions(-) create mode 100644 site/en/docs/extensions/mv3/shared_modules/index.md diff --git a/site/en/docs/extensions/mv3/manifest/default_locale/index.md b/site/en/docs/extensions/mv3/manifest/default_locale/index.md index 384bdf7e44f5..39fb146bb24d 100644 --- a/site/en/docs/extensions/mv3/manifest/default_locale/index.md +++ b/site/en/docs/extensions/mv3/manifest/default_locale/index.md @@ -6,8 +6,13 @@ updated: 2018-04-26 description: Reference documentation for the default_locale property of manifest.json. --- -Specifies the subdirectory of `_locales` that contains the default strings for this extension. This -field is **required** in extensions that have a `_locales` directory; it **must be absent** in -extensions that have no `_locales` directory. For details, see [Internationalization][1]. +Defines the default language of an extension that supports multiple locales. It is the name of the subdirectory in `_locales` that contains the default language for this extension. For example, the following code indicates that English is the default language: -[1]: /docs/extensions/i18n +```json +"default_locale": "en" +``` + +This field is **required** for localized extensions (those with a `_locales` directory), but **must be absent** in +extensions that have no `_locales` directory. For details, see [Internationalization][api-i18n]. + +[api-i18n]: /docs/extensions/i18n diff --git a/site/en/docs/extensions/mv3/manifest/description/index.md b/site/en/docs/extensions/mv3/manifest/description/index.md index 4150449108b1..f493829414f7 100644 --- a/site/en/docs/extensions/mv3/manifest/description/index.md +++ b/site/en/docs/extensions/mv3/manifest/description/index.md @@ -7,9 +7,15 @@ description: Reference documentation for the description property of manifest.js --- A plain text string (no HTML or other formatting; no more than 132 characters) that describes the -extension. The description should be suitable for both the browser's extension management UI and the -[Chrome Web Store][1]. You can specify locale-specific strings for this field; see -[Internationalization][2] for details. +extension. For example: -[1]: https://chrome.google.com/webstore -[2]: /docs/extensions/i18n +```json +"description": "A description of my extension" +``` + +The description should be suitable for both the browser's Extensions page (chrome://extensions) and the +[Chrome Web Store][cws]. You can specify locale-specific strings for this field; see +[Internationalization][api-i18n] for details. + +[cws]: https://chrome.google.com/webstore +[api-i18n]: /docs/extensions/i18n diff --git a/site/en/docs/extensions/mv3/manifest/externally_connectable/index.md b/site/en/docs/extensions/mv3/manifest/externally_connectable/index.md index c7c059efedeb..4a82166ec03b 100644 --- a/site/en/docs/extensions/mv3/manifest/externally_connectable/index.md +++ b/site/en/docs/extensions/mv3/manifest/externally_connectable/index.md @@ -1,22 +1,21 @@ --- -layout: "layouts/doc-post.njk" -title: "externally_connectable" +layout: 'layouts/doc-post.njk' +title: 'externally_connectable' date: 2013-08-21 updated: 2014-10-31 description: Reference documentation for the externally_connectable property of manifest.json. --- -The `externally_connectable` manifest property declares which extensions, apps, and web pages can -connect to your extension via [runtime.connect][1] and [runtime.sendMessage][2]. +The `externally_connectable` manifest property declares which extensions and web pages can +connect to your extension via [runtime.connect][runtime-connect] and [runtime.sendMessage][runtime-sendmessage]. -For a tutorial on message passing see [cross-extension and app messaging][3] and [sending messages -from web pages][4]. +For a tutorial on message passing see [cross-extension messaging][messages-other-exts] and [sending messages +from web pages][messages-webpage]. ## Connecting without externally_connectable {: #without-externally-connectable } -If `externally_connectable` is not declared in your extension's manifest, all extensions and apps -can connect, but no webpages can connect. As a consequence, when updating your manifest to use -`externally_connectable`, if `"ids": ["*"]` is not specified then other extensions and apps will +If the `externally_connectable` key is **_not_** declared in your extension's manifest, all extensions can connect, but no webpages can connect. As a consequence, when updating your manifest to use +`externally_connectable`, if `"ids": ["*"]` is not specified then other extensions will lose the ability to connect to your extension. This may be an unintended consequence, so keep it in mind. @@ -26,28 +25,17 @@ mind. { "name": "My externally connectable extension", "externally_connectable": { - // Extension and app IDs. If this field is not specified, no - // extensions or apps can connect. "ids": [ "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", ... - // Alternatively, to match all extensions and apps, specify only - // "*". - "*" ], - // Match patterns for web pages. Does not affect content scripts. // If this field is not specified, no webpages can connect. "matches": [ "https://*.google.com/*", "*://*.chromium.org/*", ... ], - // Indicates that the extension would like to make use of the TLS - // channel ID of the web page connecting to it. The web page must - // also opt to send the TLS channel ID to the extension via setting - // includeTlsChannelId to true in runtime.connect's connectInfo - // or runtime.sendMessage's options. "accepts_tls_channel_id": false }, ... @@ -56,38 +44,32 @@ mind. ## Reference {: #reference } -The externally_connectable manifest key can have the following properties: +The `"externally_connectable"` manifest key includes the following _optional_ properties: -- **`ids` (array of string)** - optional +`"ids"` +: The IDs of extensions that are allowed to connect. If left empty or unspecified, no extensions or apps can connect. The wildcard `"*"` will allow all extensions and apps to connect. - The IDs of extensions or apps that are allowed to connect. If left empty or unspecified, no - extensions or apps can connect. +`"matches"` +: The URL patterns for _web pages_ that are allowed to connect. If left empty or unspecified, no web pages can connect. Patterns cannot include wildcard domains nor subdomains of [(effective) top level domains][public-suffix], for example: - The wildcard `"*"` will allow all extensions and apps to connect. +| ✅ Valid URLs | ❌ Invalid URLs | +|---------------------------|-----------------------| +| `*://example.com/` | `*://example.com/one/` | +| `http://*.example.org/*` | `` | +| `https://example.com/*` | `http://*/*` | -- **`matches` (array of string)** - optional +`"accepts_tls_channel_id"` +: Enables the extension to make use of the TLS channel ID of the web page connecting to it. The web page must also opt to send the [TLS channel ID][runtime-tls-channel] to the extension via setting +`includeTlsChannelId` to `true` in runtime.connect's [connectInfo][connect-include-tls] or runtime.sendMessage's [options][options-include-tls]. If set to `false`, +[runtime.MessageSender.tlsChannelId][runtime-tls-channel] will never be set under any circumstance. - The URL patterns for _web pages_ that are allowed to connect. _This does not affect content - scripts._ If left empty or unspecified, no web pages can connect. +This does not affect content scripts. - Patterns cannot include wildcard domains nor subdomains of [(effective) top level domains][7]; - `*://google.com/*` and `http://*.chromium.org/*` are valid, while ``, `http://*/*`, - `*://*.com/*`, and even `http://*.appspot.com/*` are not. - -- **`accepts_tls_channel_id` (boolean)** - optional - - If `true`, messages sent via [runtime.connect][8] or [runtime.sendMessage][9] will set - [runtime.MessageSender.tlsChannelId][10] if those methods request it to be. If `false`, - [runtime.MessageSender.tlsChannelId][11] will never be set under any circumstance. - -[1]: /docs/extensions/runtime#method-connect -[2]: /docs/extensions/runtime#method-sendMessage -[3]: /docs/extensions/mv3/messaging#external -[4]: /docs/extensions/mv3/messaging#external-webpage -[5]: /docs/extensions/runtime#method-connect -[6]: /docs/extensions/runtime#method-sendMessage -[7]: http://publicsuffix.org/list/ -[8]: /docs/extensions/runtime#method-connect -[9]: /docs/extensions/runtime#method-sendMessage -[10]: /docs/extensions/runtime#property-MessageSender-tlsChannelId -[11]: /docs/extensions/runtime#property-MessageSender-tlsChannelId +[connect-include-tls]: /docs/extensions/reference/runtime/#type-connect-connectInfo +[messages-other-ext]: /docs/extensions/mv3/messaging#external +[messages-webpage]: /docs/extensions/mv3/messaging#external-webpage +[options-include-tls]: /docs/extensions/reference/runtime/#property-sendMessage-options-includeTlsChannelId +[public-suffix]: http://publicsuffix.org/list/ +[runtime-connect]: /docs/extensions/reference/runtime#method-connect +[runtime-sendmessage]: /docs/extensions/reference/runtime#method-sendMessage +[runtime-tls-channel]: /docs/extensions/runtime#property-MessageSender-tlsChannelId diff --git a/site/en/docs/extensions/mv3/manifest/icons/index.md b/site/en/docs/extensions/mv3/manifest/icons/index.md index ff4931cc726e..848a80e6050b 100644 --- a/site/en/docs/extensions/mv3/manifest/icons/index.md +++ b/site/en/docs/extensions/mv3/manifest/icons/index.md @@ -34,8 +34,7 @@ Here's an example of how to declare the icons in the manifest: {% Aside %} You may provide icons of any other size you wish, and Chrome will attempt to use the best size where -appropriate. For example, Windows often requires 32-pixel icons, and if the app includes a 32-pixel -icon, Chrome will choose that instead of shrinking a 48-pixel icon. +appropriate. {% endAside %} diff --git a/site/en/docs/extensions/mv3/manifest/manifest_version/index.md b/site/en/docs/extensions/mv3/manifest/manifest_version/index.md index 776fc2daa19f..deb7f47a21dc 100644 --- a/site/en/docs/extensions/mv3/manifest/manifest_version/index.md +++ b/site/en/docs/extensions/mv3/manifest/manifest_version/index.md @@ -6,7 +6,7 @@ updated: 2021-07-29 description: Reference documentation for the manifest_version property of manifest.json. --- -An integer specifying the version of the manifest file format your package requires. For example: +An integer specifying the version of the manifest file format your package requires. This key is required. For example: ```json "manifest_version": 3 @@ -17,9 +17,9 @@ Supported values for this key are: * `3`: Use the [Manifest V3][mv3] format and associated feature set. * `2`: Use the [Manifest V2][mv2] format and associated feature set. -The current version is Manifest V3. Manifest V2 is also currently permitted, but will be phased out -in the future (see [Manifest V2 support timeline][mv2-timeline] for more details). There will be -other manifest versions in the future (V4 and beyond) but these aren't scheduled yet. +The current version is Manifest V3. The Chrome Web Store no longer accepts manifest V2 extensions +(see [Manifest V2 support timeline[mv2-timeline] for more details). There will be other manifest +versions in the future (V4 and beyond), but these aren't scheduled yet. [mv3]: /docs/extensions/mv3/intro/mv3-overview/ [mv2]: /docs/extensions/mv2/manifest/ diff --git a/site/en/docs/extensions/mv3/manifest/name/index.md b/site/en/docs/extensions/mv3/manifest/name/index.md index abfaa0300c73..27929ce2914f 100644 --- a/site/en/docs/extensions/mv3/manifest/name/index.md +++ b/site/en/docs/extensions/mv3/manifest/name/index.md @@ -7,7 +7,16 @@ description: Reference documentation for the name and short_name properties of m --- The `name` and `short_name` manifest properties are short, plain text strings that identify the -extension. You can specify locale-specific strings for both fields; see [Internationalization][1] +extension. For example: + +```json +{ + "name": "My extension name", + "short_name": "My short extension name" +} +``` + +You can specify locale-specific strings for both fields; see [Internationalization][api-i18n] for details. ## Name {: #name } @@ -16,18 +25,15 @@ The `name` (maximum of 45 characters) is the primary identifier of the extension field. It is displayed in the following locations: - Install dialog -- Extension management UI -- [Chrome Web Store][2] +- Extensions page (chrome://extensions) +- [Chrome Web Store][cws] ## Short Name {: #short_name } The `short_name` (maximum of 12 characters recommended) is a short version of the extension's name. It is an optional field and if not specified, the `name` will be used, though it will likely be truncated. The short name is typically used where there is insufficient space to display the full -name, such as: - -- App launcher -- New Tab page +name. -[1]: /docs/extensions/i18n -[2]: https://chrome.google.com/webstore +[api-i18n]: /docs/extensions/i18n +[cws]: https://chrome.google.com/webstore diff --git a/site/en/docs/extensions/mv3/manifest/version/index.md b/site/en/docs/extensions/mv3/manifest/version/index.md index 30577822f2b0..fc301e83ee54 100644 --- a/site/en/docs/extensions/mv3/manifest/version/index.md +++ b/site/en/docs/extensions/mv3/manifest/version/index.md @@ -9,9 +9,8 @@ description: Reference documentation for the version property of manifest.json. One to four dot-separated integers identifying the version of this extension. A couple of rules apply to the integers: -- They must be between 0 and 65535, inclusive. For example, 99999 is invalid because it is too - large. -- Non-zero integers can't start with 0. For example, 032 is invalid because it starts with a zero. +- The integers must be between 0 and 65535, inclusive. +- Non-zero integers can't start with 0. For example, 032 is invalid because it begins with a zero. - They must not be all zero. For example, 0 and 0.0.0.0 are invalid while 0.1.0.0 is valid. Here are some examples of valid versions: @@ -21,21 +20,18 @@ Here are some examples of valid versions: - `"version": "2.10.2"` - `"version": "3.1.2.4567"` -The autoupdate system compares versions to determine whether an installed extension needs to be -updated. If the published extension has a newer version string than the installed extension, then +If the published extension has a newer version string than the installed extension, then the extension is automatically updated. -The comparison starts with the leftmost integers. If those integers are equal, the integers to the -right are compared, and so on. For example, 1.2.0 is a newer version than 1.1.9.9999. +The comparison starts with the leftmost integers. Then, if those integers are equal, the integers to +the right are compared, and so on. For example, 1.2.0 is a newer version than 1.1.9.9999. -A missing integer is equal to zero. For example, 1.1.9.9999 is newer than 1.1 and 1.1.9.9999 is +A missing integer is equal to zero. For example, 1.1.9.9999 is newer than 1.1, and 1.1.9.9999 is older than 1.2. -For more information, see [Autoupdating][1]. - ## Version Name {: #version_name } -In addition to the version field, which is used for update purposes, version_name can be set to a +In addition to the `"version"` field, which is used for update purposes, `"version_name"` can be set to a descriptive version string and will be used for display purposes if present. Here are some examples of version names: @@ -45,5 +41,3 @@ Here are some examples of version names: - `"version_name": "3.1.2.4567"` If no version_name is present, the version field will be used for display purposes as well. - -[1]: /docs/extensions/mv3/autoupdate diff --git a/site/en/docs/extensions/mv3/shared_modules/index.md b/site/en/docs/extensions/mv3/shared_modules/index.md new file mode 100644 index 000000000000..657c0e12a40d --- /dev/null +++ b/site/en/docs/extensions/mv3/shared_modules/index.md @@ -0,0 +1,95 @@ +--- +layout: "layouts/doc-post.njk" +title: "Shared modules" +date: 2015-01-05 +updated: 2018-05-22 +description: How to share code between Chrome Extensions. +--- + +_Shared Modules_ are permissionless collections of resources that can be shared between other +extensions and apps. Common uses of Shared Modules are: + +- As an API. You can distribute a Shared Module that can provide HTML, JS, and other source to + provide an API which can be updated independently of the extensions that depend on it. This can be + useful for runtimes and game engines, where apps are often smaller payloads of data that run on + the Shared Module's code. +- As a download optimization. The Shared Module contains common resources used by many extensions. + It's downloaded once, the first time a dependent extension is installed. + +## Manifest {: #manifest } + +Shared Modules are used through two [manifest][1] fields: export and import. + +The _export_ field indicates an extension is a Shared Module that exports its resources: + +```json +{ + "version": "1.0", + "name": "My Shared Module", + "export": { + // Optional list of extension IDs explicitly allowed to + // import this Shared Module's resources. If no allowlist + // is given, all extensions are allowed to import it. + "allowlist": [ + "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", + "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb" + ] + } + // Note: no permissions are allowed in Shared Modules +} +``` + +The _import_ field is used by extensions and apps to declare that they depend on the resources from +particular Shared Modules: + +```json +{ + "version": "1.0", + "name": "My Importing Extension", + ... + "import": [ + {"id": "cccccccccccccccccccccccccccccccc"}, + {"id": "dddddddddddddddddddddddddddddddd" + "minimum_version": "0.5" // optional + }, + ] +} +``` + +## Accessing resources {: #accessing_resources } + +Shared Module resources are accessed by a reserved path _\_modules/SHARED\_MODULE\_ID_ in the root +of your importing extension. For example, to include the script 'foo.js' from a Shared Module with +ID "cccccccccccccccccccccccccccccccc", use this path from the root of your extension: + +```html +