Firefox Webextension: How Do I Run Code Prior To Disable/uninstall?

I have recently converted a GreaseMonkey script of mine into a WebExtension, just to get a first impression of the process. Now I have a reached a point where it would be nice to d

Solution 1:

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.varCANARY_CLASS = '_' + crypto.getRandomValues(newUint32Array(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);
        }
    });
    returntrue; // 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;
    varCANARY_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.

Solution 2:

Your initial wording was somewhat unclear as to exactly what you desire. Thus, this answer also contains information on one way you could receive a notification of the uninstall, under some conditions.

Run code in your WebExtension add-on prior to uninstall/disable: No, even if it was supported, the runtime.onSuspend event would not do what you want. It's used to signal Event Pages that they are about to be unloaded. Even Pages are unloaded routinely when the handling of the events they are listening for has completed. It is not an indication that the extension is being uninstalled.

"Determine" that your "WebExtension was disabled/uninstalled": If your question is really what you state in the last line of your question: "... is there a way to determine whether a WebExtension was disabled/uninstalled?" Then, it looks like you could use runtime.setUninstallURL(), which was implemented as of Firefox 47. This will allow you to set a URL to visit when the add-on is uninstalled. This could be used on your server to note that the add-on was uninstalled. It does not inform your WebExtension that it was uninstalled, nor permit you to run code in your WebExtension when that happens.

Unfortunately, you can not use detecting, in your WebExtension, that this URL was visited as indicating your WebExtension is being uninstalled/disabled. Based on testing, this URL is visited after the WebExtension has been completely uninstalled. In addition, it is not visited upon the WebExtension being disabled, nor when uninstalled after being disabled. It is only visited when the WebExtension is uninstalled while the add-on is enabled. From the fact that this is a JavaScript call which is only run when the extension is enabled, one would expect that the page would only be opened when leaving the enabled state.

Testing was done by adding the following line to a WebExtension and seeing when the page was opened:

chrome.runtime.setUninstallURL("http://www.google.com");

Given how this actually functions (only visited if the WebExtension is enabled and directly uninstalled), using this as "a way to determine whether a WebExtension was disabled/uninstalled" will only be partially effective. As should be clear, you will not be notified by a visit to this URL if the add-on is disabled prior to being uninstalled.