The other answer is incorrect. The first part (about the onSuspend event) is factually incorrect. The part about setUninstallURL is relevant, but does not answer the question since it does not allow you to restore tabs to their original state (as you asked in the question).
In this answer I will first clear the misconception about runtime.onSuspend, and then explain how you can run code for a content script when an extension is disabled.
About runtime.onSuspend
The chrome.runtime.onSuspend and chrome.runtime.onSuspendCanceled events have nothing to do with a disabled/uninstalled extension. The events are defined for event pages, which are basically background pages that are suspended (unloaded) after a period of inactivity. When the event page is about to unload due to suspension, runtime.onSuspend is called. If an extension API is called during this event (e.g. sending an extension message), the suspension will be canceled and trigger the onSuspendCanceled event.
When an extension is unloading because of a browser shutdown or an uninstallation, the lifetime of the extension cannot be extended. Thus you cannot rely on these events to run asynchronous tasks (such as cleaning up tabs from the background page).
Furthermore, these events are not available in content scripts (only extension pages such as background pages), so these cannot be used to synchronously clean up content script logic.
From the above it should be obvious that runtime.onSuspend is not remotely relevant for the goal of clean-up upon disable. Not in Chrome, let alone Firefox (Firefox does not support event pages, these events would be meaningless).
Running code in tabs/content scripts upon extension disable/uninstall
A common pattern in Chrome extensions is to use the port.onDisconnect event to detect that the background page has unloaded, and use that to infer that the extension might have unloaded (combined with option 1 of this method for a higher accuracy). Chrome's content scripts are kept around after an extension is disabled, so this can be used to run asynchronous clean-up code.
This is not possible in Firefox, because the execution context of a content script is destroyed when a Firefox extension is disabled, before the port.onDisconnect event has a chance to fire (at least, until bugzil.la/1223425 is fixed).
Despite these constraints, it is still possible to run clean up logic for a content script when an add-on is disabled. This method is based on the fact that in Firefox, style sheets inserted with tabs.insertCSS are removed when an add-on is disabled.
I will discuss two ways to exploit this characteristic. The first method allows execution of arbitrary code. The second method does not provide execution of arbitrary code, but it is simpler and sufficient if you only want to hide some extension-inserted DOM elements.
Method 1: Run code in page when extension is disabled
One of the ways to observe style changes is by declaring CSS transitions and using transition events to detect CSS property changes.
For this to be helpful, you need to construct a style sheet in such a way that it only affects your HTML elements. So you need to generate a unique selector (class name, ID, ...) and use that for your HTML element(s) and style sheet.
This is code that you have to put in your background script:
chrome.runtime.onMessage.addListener(function(message, sender, sendResponse) {
if (message !== 'getStyleCanary') return;
// Generate a random class name, insert a style sheet and send
// the class back to the caller if successful.
var CANARY_CLASS = '_' + crypto.getRandomValues(new Uint32Array(2)).join('');
var code = '.' + CANARY_CLASS + ' { opacity: 0 !important; }';
chrome.tabs.insertCSS(sender.tab.id, {
code,
frameId: sender.frameId,
runAt: 'document_start',
}, function() {
if (chrome.runtime.lastError) {
// Failed to inject. Frame unloaded?
sendResponse();
} else {
sendResponse(CANARY_CLASS);
}
});
return true; // We will asynchronously call sendResponse.
});
In the content script:
chrome.runtime.sendMessage('getStyleCanary', function(CANARY_CLASS) {
if (!CANARY_CLASS) {
// Background was unable to insert a style sheet.
// NOTE: Consider retry sending the message in case
// the background page was not ready yet.
return;
}
var s = document.createElement('script');
s.src = chrome.runtime.getURL('canaryscript.js');
s.onload = s.remove;
s.dataset.canaryClass = CANARY_CLASS;
// This function will become available to the page and be used
// by canaryscript.js. NOTE: exportFunction is Firefox-only.
exportFunction(function() {}, s, {defineAs: 'checkCanary'});
(document.body || document.documentElement).appendChild(s);
});
I use a script tag above, because it is the only way to run a script in the page without being blocked by the page's content security policy. Make sure that you add canaryscript.js to web_accessible_resources in manifest.json, or else the script won't load.
If running the cleanup code is not critical (e.g. because you also use method 2 which I explain later), then you should preferably use inline scripts instead of external scripts (i.e. use s.textContent = '<content of canaryscript.js>' instead of s.src = ...). This is because using .src with extension resources introduces a fingerprinting vulnerability to Firefox (bug 1372288).
This is the content of canaryscript.js:
(function() {
// Thes two properties are set in the content script.
var checkCanary = document.currentScript.checkCanary;
var CANARY_CLASS = document.currentScript.dataset.canaryClass;
var canary = document.createElement('span');
canary.className = CANARY_CLASS;
// The inserted style sheet has opacity:0. Upon removal a transition occurs.
canary.style.opacity = '1';
canary.style.transitionProperty = 'opacity';
// Wait a short while to make sure that the content script destruction
// finishes before the style sheet is removed.
canary.style.transitionDelay = '100ms';
canary.style.transitionDuration = '1ms';
canary.addEventListener('transitionstart', function() {
// To avoid inadvertently running clean-up logic when the event
// is triggered by other means, check whether the content script
// was really destroyed.
try {
// checkCanary will throw if the content script was destroyed.
checkCanary();
// If we got here, the content script is still valid.
return;
} catch (e) {
}
canary.remove();
// TODO: Put the rest of your clean up code here.
});
(document.body || document.documentElement).appendChild(canary);
})();
Note: CSS transition events are only fired if the tab is active. If the tab is inactive, the transition event will not fire until the tab is shown.
Note: exportFunction is a Firefox-only extension method to define a function in a different execution context (in the above example, the function was defined in the page's context, available to scripts running in that page).
All other APIs are available in other browsers too (Chrome/Opera/Edge), but the code cannot be used to detect disabled extensions, because style sheets from tabs.insertCSS are not removed upin uninstall (I only tested with Chrome; it might work in Edge).
Method 2: Visual restoration upon uninstallation
Method 1 allows you to run arbitrary code, such as removing all elements that you inserted in the page. As an alternative to removing the elements from the DOM, you can also choose to hide the elements through CSS.
Below I show how you can modify method 1 to hide the elements without running other code (such as canaryscript.js).
When your content script creates an element for insertion in the DOM, you hide it with an inline style:
var someUI = document.createElement('div');
someUI.style.display = 'none'; // <-- Hidden
// CANARY_CLASS is the random class (prefix) from the background page.
someUI.classList.add(CANARY_CLASS + 'block');
// ... other custom logic, and add to document.
In the style sheet that you add with tabs.insertCSS, you then define the desired display value, with the !important flag so that the inline style is overridden:
// Put this snippet after "var code = '.' + CANARY_CLASS, above.
code += '.' + CANARY_CLASS + 'block {display: block !important;}';
The above example is intentionally generic. If you have multiple UI elements with different CSS display values (e.g. block, inline, ...), then you can add multiple of these lines to re-use the framework that I provided.
To show the simplicity of method 2 over method 1: you can use the same background script (with the above modification), and use the following in the content script:
// Example: Some UI in the content script that you want to clean up.
var someUI = document.createElement('div');
someUI.textContent = 'Example: This is a test';
document.body.appendChild(someUI);
// Clean-up is optional and a best-effort attempt.
chrome.runtime.sendMessage('getStyleCanary', function(CANARY_CLASS) {
if (!CANARY_CLASS) {
// Background was unable to insert a style sheet.
// Do not add clean-up classes.
return;
}
someUI.classList.add(CANARY_CLASS + 'block');
someUI.style.display = 'none';
});
If your extension has more than one element, consider caching the value of CANARY_CLASS in a local variable so that you only insert one new style sheet per execution context.
