Quick Start
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:
- Your Chrome Extension is using Manifest V3
- 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
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:
Alert window asking for permission to Read and change all your data on all websites
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",
"tabs",
"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>");
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";
let mellowtel;
(async () => {
mellowtel = new Mellowtel("<configuration_key>"); //Change here 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:
-
Using the recommended implementation with the pre-built page provided by Mellowtel.
-
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.
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