diff --git a/api-samples/declarativeNetRequest/url-blocker/README.md b/api-samples/declarativeNetRequest/url-blocker/README.md index f16bfbf4c8..75925f0b11 100644 --- a/api-samples/declarativeNetRequest/url-blocker/README.md +++ b/api-samples/declarativeNetRequest/url-blocker/README.md @@ -9,3 +9,10 @@ Once this extension is installed, any requests made in the main frame to example ## Implementation Notes This sample uses the `chrome.declarativeNetRequest.onRuleMatchedDebug` event which is only available in unpacked extensions. + +## Running this extension + +1. Clone this repository. +2. Load this directory in Chrome as an [unpacked extension](https://developer.chrome.com/docs/extensions/mv3/getstarted/development-basics/#load-unpacked). +3. Select and open the extension from the extensions menu. +4. To test the extension, click on 'Sample minute' to set an alarm of 1 minute, post which a notification appears in the system tray. diff --git a/api-samples/printing/README.md b/api-samples/printing/README.md index 25caa7c752..040e783865 100644 --- a/api-samples/printing/README.md +++ b/api-samples/printing/README.md @@ -1,4 +1,4 @@ -# chrome.printing +# Chrome.printing Sample This sample demonstrates all four methods of the `chrome.printing` namespace. @@ -13,3 +13,10 @@ If the **Roll Printers** checkbox is selected, only printers capable of roll pri ## Implementation Notes Before Chrome 120, `submitJob()` function throws an error when returning a promise. + +## Running this extension + +1. Clone this repository. +2. Load this directory in Chrome as an [unpacked extension](https://developer.chrome.com/docs/extensions/mv3/getstarted/development-basics/#load-unpacked). +3. Select and open the extension from the extensions menu. +4. To test the extension, click on 'Sample minute' to set an alarm of 1 minute, post which a notification appears in the system tray. diff --git a/functional-samples/cookbook.sidepanel-global/README.md b/functional-samples/cookbook.sidepanel-global/README.md index 4ca70b42aa..4fbe63cf0e 100644 --- a/functional-samples/cookbook.sidepanel-global/README.md +++ b/functional-samples/cookbook.sidepanel-global/README.md @@ -2,14 +2,17 @@ This example demonstrates how to display the same side panel on every site using the [Side Panel API](https://developer.chrome.com/docs/extensions/reference/sidePanel/). +## Overview + +The example showcases the implementation of a global side panel that remains consistent across all websites. Users can access the side panel UI and select the "Global side panel" option to display the same panel regardless of the webpage they are currently visiting. + +## Implementation Notes + +_Add any information that doesn't fit elsewhere in the README._ + ## Running this extension 1. Clone this repository. 2. Load this directory in Chrome as an [unpacked extension](https://developer.chrome.com/docs/extensions/mv3/getstarted/development-basics/#load-unpacked). 3. Open the side panel UI - - Global side panel - 4. Choose the "Global side panel". - - Global side panel diff --git a/functional-samples/cookbook.sidepanel-multiple/README.md b/functional-samples/cookbook.sidepanel-multiple/README.md index 1f08bf803d..0a48a0e620 100644 --- a/functional-samples/cookbook.sidepanel-multiple/README.md +++ b/functional-samples/cookbook.sidepanel-multiple/README.md @@ -1,4 +1,8 @@ -# Multiple side panels example +# Multiple side panels sample + +This sample demonstrates the usage of `sidepanel.getOptions()` to retrieve the current side panel and switch between multiple side panels. + +## Overview You can use [`sidepanel.getOptions()`](https://developer.chrome.com/docs/extensions/reference/sidePanel/#method-getOptions) to retrieve the current side panel and switch between side panels. This example sets a welcome side panel when the extension is first installed, then when the user navigates to a different tab, it replaces it with the main side panel. @@ -8,9 +12,4 @@ You can use [`sidepanel.getOptions()`](https://developer.chrome.com/docs/extensi 2. Load this directory in Chrome as an [unpacked extension](https://developer.chrome.com/docs/extensions/mv3/getstarted/development-basics/#load-unpacked). 3. Open the side panel UI 4. Choose "Multiple side panels" to see the welcome page. - -Welcome side panel - 5. Navigate to https://developer.chrome.com to see the main side panel. - -Main side panel diff --git a/functional-samples/cookbook.sidepanel-open/README.md b/functional-samples/cookbook.sidepanel-open/README.md index 7d6998e25b..6d11e3331f 100644 --- a/functional-samples/cookbook.sidepanel-open/README.md +++ b/functional-samples/cookbook.sidepanel-open/README.md @@ -1,11 +1,12 @@ -# Opening the side panel through a user interaction +# SidePanel Open Sample -This example demonstrates using [`chrome.sidePanel.open()`](https://developer.chrome.com/docs/extensions/reference/sidePanel/#method-open) to open a global side panel through a context menu click and a tab-specific side panel by clicking a button in an extension page or a button click injected by a content script. This feature will be available starting **Chrome 116**. +This sample demonstrates the functionality of `chrome.sidePanel.open()`. -## Running this extension +## Overview -1. Clone this repository. -2. Load this directory in Chrome as an [unpacked extension](https://developer.chrome.com/docs/extensions/mv3/getstarted/development-basics/#load-unpacked). +This example demonstrates using [`chrome.sidePanel.open()`](https://developer.chrome.com/docs/extensions/reference/sidePanel/#method-open) to open a global side panel through a context menu click and a tab-specific side panel by clicking a button in an extension page or a button click injected by a content script. This feature will be available starting **Chrome 116**. + +## Implementation Notes ### Test with a context menu @@ -23,3 +24,10 @@ This example demonstrates using [`chrome.sidePanel.open()`](https://developer.ch 1. Navigate to [google.com](http://www.google.com/). 2. Scroll to the very bottom of the page. 3. Click on the "Open side panel" button. + +## Running this extension + +1. Clone this repository. +2. Load this directory in Chrome as an [unpacked extension](https://developer.chrome.com/docs/extensions/mv3/getstarted/development-basics/#load-unpacked). +3. Select and open the extension from the extensions menu. +4. To test the extension, click on 'Sample minute' to set an alarm of 1 minute, post which a notification appears in the system tray. diff --git a/functional-samples/reference.mv3-content-scripts/README.md b/functional-samples/reference.mv3-content-scripts/README.md index dc7ad5fb49..b9c17a284a 100644 --- a/functional-samples/reference.mv3-content-scripts/README.md +++ b/functional-samples/reference.mv3-content-scripts/README.md @@ -1,3 +1,18 @@ -Sample code for the [Executing arbitrary strings][section] section of the MV3 migration documentation. +# MV3 Content Scripts Sample -[section]: https://developer.chrome.com/docs/extensions/mv3/intro/mv3-migration/#executing-arbitrary-strings +This sample demonstrates executing arbitrary strings in a Chrome extension, as described in the [Executing arbitrary strings][https://developer.chrome.com/docs/extensions/mv3/intro/mv3-migration/#executing-arbitrary-strings] section of the MV3 migration documentation. + +## Overview + +This sample provides a basic HTML page with buttons to inject a file or execute a function into the current tab using Chrome's scripting API. The `inject-file` button injects a content script file, while the `inject-function` button executes a predefined function. This demonstrates how to dynamically inject code into web pages from a Chrome extension. + +## Implementation Notes + +Ensure that the necessary permissions for scripting and accessing the active tab are declared in the extension's manifest file. Additionally, modify the `popup.js` file to handle button click events and execute the corresponding scripts. + +## Running this extension + +1. Clone this repository. +2. Load this directory in Chrome as an [unpacked extension](https://developer.chrome.com/docs/extensions/mv3/getstarted/development-basics/#load-unpacked). +3. Select and open the extension from the extensions menu. +4. To test the extension, click on 'Sample minute' to set an alarm of 1 minute, post which a notification appears in the system tray. diff --git a/functional-samples/sample.catifier/README.md b/functional-samples/sample.catifier/README.md index fe31d0d012..7130d5c7b2 100644 --- a/functional-samples/sample.catifier/README.md +++ b/functional-samples/sample.catifier/README.md @@ -1,8 +1,18 @@ -# Catifier +# Catifier Sample -When the extension is enabled, it replaces every image of extension jpg or jpeg, with [this](https://i.chzbgr.com/completestore/12/8/23/S__rxG9hIUK4sNuMdTIY9w2.jpg) image. +This sample demonstrates a Chrome extension called Catifier, which replaces every `jpg` or `jpeg` image on webpages with a specific cat image. -## Testing the extension +## Overview -1. Follow the instructions to load an [unpacked extension](https://developer.chrome.com/docs/extensions/mv3/getstarted/development-basics/#load-unpacked). -2. Navigate to any website, you should see every jpg or jpeg image being replaced by an image of a cat. +Catifier modifies the content of webpages by intercepting requests for jpg or jpeg images and replacing them with a predefined cat image sourced from [this](https://i.chzbgr.com/completestore/12/8/23/S__rxG9hIUK4sNuMdTIY9w2.jpg) image. + +## Implementation Notes + +Catifier utilizes the capabilities of Chrome extensions to intercept and modify webpage content dynamically. It demonstrates how extensions can be used to customize the browsing experience for users. + +## Running this extension + +1. Clone this repository. +2. Load this directory in Chrome as an [unpacked extension](https://developer.chrome.com/docs/extensions/mv3/getstarted/development-basics/#load-unpacked). +3. Select and open the extension from the extensions menu. +4. To test the extension, click on 'Sample minute' to set an alarm of 1 minute, post which a notification appears in the system tray. diff --git a/functional-samples/sample.co2meter/README.md b/functional-samples/sample.co2meter/README.md index a3f357b6e0..4eb559927f 100644 --- a/functional-samples/sample.co2meter/README.md +++ b/functional-samples/sample.co2meter/README.md @@ -1,17 +1,14 @@ -# **Sample CO₂ Meter Chrome Extension** +# CO₂ Meter Sample -The extension uses [WebHID](https://developer.chrome.com/en/articles/hid/) to access a device for measuring the CO₂ level and temperature in your surroundings. +This sample demonstrates the functionality of a Chrome extension that utilizes [WebHID](https://developer.chrome.com/en/articles/hid/) to access a device for measuring CO₂ levels and temperature in the surroundings. -## **Testing the extension** +## Overview -1. Follow the instructions to load an [unpacked extension](https://developer.chrome.com/docs/extensions/mv3/getstarted/development-basics/#load-unpacked). -2. Connect the CO₂ meter (currently it only supports the [CO2Mini Indoor Air Quality Monitor](https://www.co2meter.com/products/co2mini-co2-indoor-air-quality-monitor) from CO2Meter.com). -3. Open the extension popup window and click “Settings” button to go to the settings page. -4. Click the “Grant CO2 meter permission” button and grant the permission to the CO₂ meter. +The extension allows users to connect a CO₂ meter, specifically supporting the CO2Mini Indoor Air Quality Monitor from CO2Meter.com. It provides instructions for testing the extension, including loading it as an unpacked extension, connecting the CO₂ meter, and granting permission to access the device. The extension processes input reports from the device and displays the results in the popup window or settings page. -Following the above steps, the device connection session to the CO₂ meter will be created when the extension is running. The input reports from the device will be processed and are visble from the popup window or settings page. +## Implementation Notes -## **Design** +### **Design** - [co2_meter.js](modules/co2_meter.js): A CO2 meter device driver layer that uses WebHID to communicate with the device. - [co2-state-iframe.js](./co2-state-iframe.js): A module to be embedded in a regular page or popup window for showing the current CO2 meter status. It listens for events from the extension service worker, such as meter readings or availability, and renders the results. @@ -21,9 +18,19 @@ Following the above steps, the device connection session to the CO₂ meter will - Initialize the CO2 meter for starting to generate reading input reports using [co2_meter.js](modules/co2_meter.js). - Broadcast events (e.g., CO2 readings, CO2 availability) to registered clients (e.g., the popup window). -## **WebHID limitations in extension service workers** +### **WebHID limitations in extension service workers** WebHID will be officially available to extension service workers in Chrome 115. Before M115, it can be enabled through the flag chrome://flags#enable-web-hid-on-extension-service-worker. However, there are limitations to the support for WebHID in extension service workers: - Before M115 with flag enabled, if the service worker is idle for longer than [30 seconds](https://source.chromium.org/chromium/chromium/src/+/main:third_party/blink/public/mojom/service_worker/service_worker.mojom;l=150;drc=ff468ef351dc107e9bb92635914e3908d763cf29) it may be terminated, closing the device connection session. This limitation will be resolved in M115. - Device connection events are not fired if the device is plugged or unplugged while the service worker is inactive. We have [crbug.com/1446487](http://crbug.com/1446487) to track the resolution of this limitation. If your extension encounters issues because of this limitation, please leave a comment in the bug about your use case and how the limitation affects your extension. + +## Running this extension + +1. Clone this repository. +2. Load this directory in Chrome as an [unpacked extension](https://developer.chrome.com/docs/extensions/mv3/getstarted/development-basics/#load-unpacked). +3. Connect the CO₂ meter (currently it only supports the [CO2Mini Indoor Air Quality Monitor](https://www.co2meter.com/products/co2mini-co2-indoor-air-quality-monitor) from CO2Meter.com). +4. Open the extension popup window and click “Settings” button to go to the settings page. +5. Click the “Grant CO2 meter permission” button and grant the permission to the CO₂ meter + +Following the above steps, the device connection session to the CO₂ meter will be created when the extension is running. The input reports from the device will be processed and are visble from the popup window or settings page. diff --git a/functional-samples/sample.sidepanel-dictionary/README.md b/functional-samples/sample.sidepanel-dictionary/README.md index 5e641901f3..422a8637eb 100644 --- a/functional-samples/sample.sidepanel-dictionary/README.md +++ b/functional-samples/sample.sidepanel-dictionary/README.md @@ -1,8 +1,10 @@ # Dictionary Side panel example -This example allows users to right-click on a word and see the definition on the side panel using the [Side Panel API](https://developer.chrome.com/docs/extensions/reference/sidePanel/). +This sample demonstrates how to use the [Side Panel API](https://developer.chrome.com/docs/extensions/reference/sidePanel/) to display word definitions in a side panel when users right-click on a word. -NOTE: This example only defines the word extensions and popup. +## Overview + +When users right-click on a word, the extension sends the selected word to the side panel, allowing them to view its definition. The extension utilizes` chrome.storage.session` to store the selected word, ensuring that it is accessible even if the side panel is not open at the moment of selection. ## Implementation Notes @@ -21,7 +23,3 @@ may not be open yet. To handle this we store the word in 3. Go to https://developer.chrome.com/docs/extensions/ 4. Right-click on the "Extensions" word. 5. Choose the "Define" context menu - -You should see the definition on the side panel - -Dictionary extension context menu diff --git a/functional-samples/tutorial.google-analytics/README.md b/functional-samples/tutorial.google-analytics/README.md index a85af1cdbc..c3f271797a 100644 --- a/functional-samples/tutorial.google-analytics/README.md +++ b/functional-samples/tutorial.google-analytics/README.md @@ -2,6 +2,14 @@ This example demonstrates how to track extension events in Google Analytics 4 using the Measurement Protocol. +## Overview + +The example provides guidance on integrating Google Analytics 4 into a Chrome extension using the Measurement Protocol. It includes instructions on obtaining the necessary `measurement_id` and `api_secret` from Google Analytics, and how to add them to the `google-analytics.js` script. The extension allows users to generate analytics events by clicking a button in the extension popup. + +## Implementation Notes + +_Add any information that doesn't fit elsewhere in the README._ + ## Running this extension 1. Clone this repository. @@ -14,5 +22,3 @@ This example demonstrates how to track extension events in Google Analytics 4 us 4. Click the extension icon to open the extension popup and click the button to generate a few analytics events. Extension popup 5. Check out the [real-time report](https://support.google.com/analytics/answer/1638635) to see how the events surface in Google Analytics. - -![Google Analytics real-time report](https://wd.imgix.net/image/6hHqS5auVgWhN0cQNQztaJx5w4M2/AQqSJb9VqalWfrQ6xSXM.png?auto=format&w=400)