Implementation of a browser Extension (Some Guidelines)

[nidhal-labidi]

Description

In this issue I outline some info necessary to understand how to deal with extensions and the difference that it has in comparison with web development.

Links / References

I think that this Udemy course is a good introduction into using Extensions (It uses React)
https://www.udemy.com/course/building-chrome-extension-to-block-ads-url-with-javascript/?couponCode=24T4MT90924B

Further information
Most important file when building extensions is Manifest file.
The latest version is V3 (the one that we should be using).
The goal of this file is to:

1. Define the purpose of the extension i.e. name, description, version...
2. Describe the HTML/CSS/JS files that compose the extension.

Example:

{
  "manifest_version": 3,
  "name": "Flottform",
  "description": "Flottform Short description",
  "version": "1.0",
  "icons": {
    "16": "images/icon-16.png",
    "32": "images/icon-32.png",
    "48": "images/icon-48.png",
    "128": "images/icon-128.png"
  },
  "action": {
    "default_icon": {
      "16": "images/icon-16.png",
      "32": "images/icon-32.png",
      "48": "images/icon-48.png",
      "128": "images/icon-128.png"
    },
    "default_popup": "path/to/html/that-will-be-shown-when-we-click-on-the-extension",
    "default_title": "Will be shown as a Tooltip when you hover over the extension icon"
  },
  "options_page":"Extra page, can be useful to allow the user to set some options (Eg. which input fields to target...), appears when we right click on the extension icon then click on `options`"
}

In Chrome Extensions Version 3, there are three main contexts: popup context, service worker context, and page context.
Each context defines permissions needed to run the script && functionality available to the script (eg. access to the popup, web page, local storage, open tabs...)

1. Popup Context

• What it is: The popup context is the HTML page you see when you click the extension icon in the Chrome toolbar. It's like a small web page with a limited lifespan.

• How it works: The popup is only alive while it's open. As soon as you click away or close it, the popup (and its JavaScript) disappears, and all its state/data is lost. (This may cause for us some issues when receiving the files i.e. if we're receiving a file or many files and the user closes the extension)

• Use case: It's useful for showing a quick UI to the user, allowing them to trigger actions or view info from the extension.

• Notes:

  • In the manifest.json file, the script is attached to the HTML page which is the value for the key: default_popup
  • Inside that script, the DOM refers to the popup itself and not the actual webpage
  • Eg. document.body.style.background="red"; --> will change the background of the popup to be red

2. Service Worker Context (Background Script)

• What it is: It doesn't have a UI but is responsible for handling events in the background (e.g., listening for alarms, responding to messages, etc.).

• How it works: The service worker is not always running. It is "event-driven," meaning it wakes up to handle events and then goes back to being idle. It can stay alive longer than the popup, but it may still "sleep" after completing tasks. (This may cause for us some issues when receiving the files)

• Use case: It’s ideal for long-running tasks, event handling (like alarms or web requests), and managing data that should persist in the background.

• Notes:

  • These scripts are defined in the manifest.json file as follows:

"background": {
    "service_worker": "background.js"
  },

3. Page Context (Content Script)

• What it is: The content script is JavaScript that runs inside the context of the web pages you visit. It's like embedding your own code into a website.

• How it works: The content script has direct access to the DOM (Document Object Model) of the page and can interact with web page elements (but not Chrome APIs directly).

• Use case: You use content scripts to modify or read the content of web pages, like changing text, adding buttons, or extracting data.

• Notes:

  • You can specify which websites you want to run content scripts on (i.e. permissions) and the user will either allow/refuse to give those permissions.
  • In the manifest.json file, the scripts are mentioned as follows

{
 "content_scripts": [ 
   {
     "matches": ["https://*/*", "http://*/*"], 
     "js": ["contentScript.js"]
   } 
 ]
}

• If you need to use Chrome API or certain sensitive information you need to ask for permissions as follows:

"permissions": ["tabs", "storage", "alarms", "notifications"]

How to Pass Data Between Contexts

To make your extension work smoothly, you'll often need to pass data between these contexts. Here are the ways you can do that:

1. Messaging (I faced some issues using this when developing my first extension)

Chrome extensions have a messaging system that lets you pass messages between the popup, service worker, and content scripts. This is the most common way to share data.

We can use chrome.runtime.sendMessage && chrome.runtime.onMessage.

2. Using chrome.storage for Persistent Data

Since popups are short-lived, you'll often lose the state/data when the popup closes. To handle this, you can store important information in chrome.storage, which allows persistent storage across sessions.

We can use for that chrome.storage.sync.set && chrome.storage.sync.get

[nidhal-labidi]

Brainstorming/ issues related to building the extension

[nidhal-labidi]

Key features of Chrome storage API (from https://developer.chrome.com/docs/extensions/reference/api/storage#usage)

1. Extension-wide Access: All extension contexts (service workers, content scripts, popups) can access the Storage API, unlike web storage which is limited in scope.
2. Persistence: Data in chrome.storage.local persists even if the user clears cache or history and remains available in incognito mode (if split incognito is enabled).
3. storage.local: Stores data locally on the device (up to 10 MB, or higher with unlimitedStorage permission). Ideal for larger, non-synced data.
4. Asynchronous & JSON-based: Data is stored as JSON serializable objects and accessed asynchronously, allowing efficient bulk read/write operations.
5. For tab IDs, they don’t change if you reload the page or navigate within the same tab. However, they do change if you open a new tab, close and reopen a tab, or open any link in a new tab.

[nidhal-labidi]

This is the directory containing information about all the extensions of one profile /Users/nidhallabidi/Library/Application Support/Google/Chrome/Profile 1/Local Extension Settings.
It's very useful when we want to see what's being stored inside of chrome.storage.local.