Tell your users what to expect in your WebExtensions version

The migration to WebExtensions APIs is picking up steam, with thousands of compatible add-ons now available on addons.mozilla.org (AMO). To ensure a good experience for the growing number of users whose legacy add-ons have been updated to WebExtensions versions, we’re encouraging developers to adopt the following best practices.

(If your new version has the same features and settings as your legacy version, your users should get a seamless transition once you update your listing, and you can safely ignore the rest of this post.)

If your new version has different features, is missing legacy features, or requires additional steps to recover custom settings, please do one or both of the following.

Update your AMO listing description

If your new version did not migrate with all of its legacy features intact, or has different features, please let your users know in the “About this Add-on” section of your listing.

If your add-on is losing some of its legacy features, let your users know if it’s because they aren’t possible with the WebExtensions API, or if you are waiting on bug fixes or new APIs to land before you can provide them. Include links to those bugs, and feel free to send people to the forum to ask about the status of bug fixes and new APIs.

Retaining your users’ settings after upgrade makes for a much better experience, and there’s still time to do it using Embedded WebExtensions. But if this is not possible for you and there is a way to recover them after upgrade, please include instructions on how to do that, and refer to them in the Version notes. Otherwise, let your users know which settings and preferences cannot be recovered.

Add an announcement with your update

If your new version is vastly different from your legacy version, consider showing a new tab to your users when they first get the update. It can be the same information you provide in your listing, but it will be more noticeable if your users don’t have to go to your listing page to see it. Be sure to show it only on the first update so it doesn’t annoy your users.

To do this, you can use the runtime.onInstalled API which can tell you when an update or install occurs:

function update(details) {

if (details.reason === 'install' || details.reason === 'update') {

browser.tabs.create({url: 'update-notes.html'});

}

}

browser.runtime.onInstalled.addListener(update);

This will open the page update-notes.html in the extension when the install occurs. For example:

For greater control, the runtime.onInstalled event also lets you know when the user updated and what their previous version was so you can tailor your release notes.

Thank you

A big thanks to all the developers who have put in the effort to migrate to the WebExtensions API. We are here to support you, so please reach out if you need help.