Here you will see how to implement the Mellowtel library in your extension project. Estimated time to complete: 5-7 minutes.

​

Requirements

Before you start, make sure that:

1. Your plugin is using Manifest V3. For FireFox plugins, you can use Manifest V2 as well.
2. Your code is organized in a compiled way, by using Webpack, Rollup, or other bundlers. If you don’t have a bundler set up, first follow the guide here

​

Install npm package

To install the npm package, you can run the following command in your terminal:

npm install mellowtel

yarn add mellowtel

​

Decide implementation

There are two ways you can implement the library in your extension.

If you are going to release the extension for the first time on the Web Store follow Option 1. If you already have the extension published on the Web Store read “How to decide?”

​

How to decide?

When you install your extension from the Web Store, does an alert window pop up asking for permission to “Read and change all your data on all websites”?

It looks like this:

If it does, you can follow Option 1. If it doesn’t, you need to follow Option 2.

​

Option 1

If you are releasing the extension for the first time on the Web Store or you are importing the library in an extension that asks for permission to operate on all websites, you can follow Option 1.

​

Set up your manifest

In your manifest.json file modify the permissions and host_permissions sections like this:

  "permissions": [
    "storage",
    "declarativeNetRequest"
  ],
  "host_permissions": [
    "\u003Call_urls\u003E"
  ],

​

Set up your service worker (background script)

In your service worker file, you need to import the mellowtel package. Note: The service worker is also known as background script.

You can copy and paste the following code into your service worker file by changing the configuration_key with your own key.

import Mellowtel from "mellowtel";

let mellowtel;

(async () => {
    mellowtel = new Mellowtel("<configuration_key>"); // Replace with your configuration key
    await mellowtel.initBackground();
})();

    import Mellowtel from "mellowtel";

mellowtel = new Mellowtel("<configuration_key>");

await mellowtel.initBackground();

​

Set up your content script

You have to import the mellowtel package in content scripts as well.

This content script should run in all_frames and <all_urls> at the document_start.

We suggest creating a new content script (e.g. content_start_mellowtel.js) where you can copy and paste the following code. Change the configuration_key with your own key.

import Mellowtel from "mellowtel";

(async () => {
    const mellowtel = new Mellowtel("<configuration_key>"); // Replace with your configuration key
    await mellowtel.initContentScript();
})();

Then remember to add also this content script in your manifest.json file in the content_scripts section alongside any other content script you already have. You can copy and paste the following code by changing the name_of_your_content_script.js with the name you chose.

  "content_scripts": [
    {
      "matches": ["<all_urls>"],
      "js": ["<name_of_your_content_script.js>"], //Change here with the name of your content script
      "run_at": "document_start",
      "all_frames": true
    }
]

​

Set up opt-in/opt-out logic

In order to activate Mellowtel, users need to explicitly opt-in to the service.

You can implement the opt-in/opt-out logic in two ways:

1. Using the recommended implementation with the pre-built page provided by Mellowtel.

2. Creating your own custom opt-in/opt-out elements and using the methods shown here

If you use the recommended implementation, open your service worker file (also known as background script) and add the following code:

chrome.runtime.onInstalled.addListener(async function(details) {
    console.log("Extension Installed or Updated");
    // If you want to handle first install and updates differently
    /**
    if(details.reason === "install"){
        // call a function to handle a first install
    } else if(details.reason === "update") {
        // call a function to handle an update
    }
    **/
    await mellowtel.generateAndOpenOptInLink();
});

​

Generate settings link

In order to let your users have complete control over their bandwidth, it is required that you leave an easily accessible way for them to change their settings at any moment.

You can generate a link by using the method generateSettingsLink(). This method will return a link that will open the Mellowtel settings page where users can decide at any time if they want to opt-in or opt-out.

This link should be placed inside the popup, options page or any other place where users can easily access it.

For example you can put it in a openSettings() function like this. You can call openSettings() on a button click or any other relevant event:

async function openSettings() {
    try {
        // Generate and manage the settings link
        const settingsLink = await mellowtel.generateSettingsLink();
        // Log the generated link for debugging
        console.log("Generated Settings Link:", settingsLink);
        // You can now use this link within a popup, options page, or any UI element
    } catch (error) {
        console.error("Error generating settings link:", error);
    }
}

Perfect! Now you are ready to send your extension to the Web Store. Follow the guide here to see how to submit your extension

​

Option 2

If you can’t implement Option 1, please reach out to us on Discord