Migrating AdBlock for Firefox to WebExtensions

AdBlock for Firefox is a fast and powerful ad blocker with over 40 million users. They are in the process of transitioning to WebExtensions, and have completed the first step of porting their data using Embedded WebExtensions. You can read more about the AdBlock extension here.

For more resources on updating your extension, please check out MDN. You can also contact us via these methods.

  1. Please provide a short background on your add-on. What does it do, when was it created, and why was it created?

    We created our original Firefox extension in 2014. We had seen some early success on Chrome and Safari and believed we could replicate that success on Firefox, which had developed a good community of users that downloaded add-ons for Firefox. It seemed like a natural place for us to be.

  1. What add-on technologies or APIs were used to build your add-on?

    The Firefox Add-On SDK was being promoted at the time, which wasn’t compatible with the Chrome Extension API, so we went through the Chrome code to identify areas where we could leverage work we had done previously. Since the APIs were a little different, we ended up having to modify some modules to use the Firefox Add-on SDK.

  1. Why did you decide to transition your add-on to WebExtensions APIs?

    With the Firefox SDK set to be deprecated, we knew our extension would slowly become unusable, so it made sense to transition to the WebExtension API. The benefit, from our standpoint, was that by using this API our software would be on a similar codebase and have similar features and functionalities to what we do on some of the other browsers we support.

  2. Walk us through the process of how you are making the transition. How was the experience of finding WebExtensions APIs to replace legacy APIs? What are some advantages and limitations?

    Last year we ported our Chrome extension to Edge, so when Firefox announced its plans, we had a good idea of what we wanted to do and how to go about it. Also, we were familiar with the WebExtension API from our years working on Chrome, but we knew we needed to educate ourselves on the differences. Fortunately, the Firefox documentation on the difference was very helpful in that education process. These pages, in particular, were helpful:

    https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Comparison_with_the_Add-on_SDK

    https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome_incompatibilities

    We did run into a few challenges. Chrome allows us to create an alert message or a confirm message from the background page (e.g., “Are you sure you want do this…”), and Firefox doesn’t allow us to do that. We use that type of messaging in our Chrome extension that we had to find a workaround for, which we were able to do. For us, this impacted our ability to message our users when they were manipulating custom filters within AdBlock, but was not a major issue.

    We hope to land Permission capabilities in Firefox 54, and you can read about its implementation progress in the WebExtensions in Firefox 53 blog post.

  1. What, if anything, will be different about your add-on when it becomes a WebExtension? Will you be able to transition with all the features intact?

    Anecdotally, the extension appears to be faster, specifically around page load times. But the big advantage, from our perspective, is that we will be able to manage the transition with almost all of our features intact. As a result, we aren’t losing any meaningful functionality of AdBlock, which was our main concern before we embarked upon this transition.

    We did notice that a few of the APIs that AdBlock utilizes are not available on Firefox for Android, so we are currently unable to release a new version of AdBlock that supports Firefox for Android. We hope to address this issue in a coming version of AdBlock.

    We have lots of work planned for Android in upcoming releases, with the goal of making ad blockers possible in Firefox 57.

  1. What advice would you give other legacy add-on developers?

    Make sure you have a migration plan that is well-tested on various versions and operating systems before you start migrating user data. One thing we learned the hard way, when we migrated our users’ data, we generated some migration messages to the console, but those message were not persisted.  It would have been more helpful to use if the messages were persisted for a period of time, to aid with debugging any user issues.

    Embedded Extensions are available as of Firefox 51 to help you transfer your user data.

  1. Anything else you’d like to add?

    If you are going to upgrade your extension, only do what’s necessary to get the current functionality working first. Don’t try and do too much in the release that you are using to migrate users over.

Privacy Features, Tab Tools & Other New WebExtensions

Tabzen is great for tab hoarders.

As of late March, addons.mozilla.org (AMO) has around 2,000 listed add-ons built with WebExtensions APIs, the new cross-browser standard for writing add-ons. Average daily installs for them total more than 5,000,000. That’s nice momentum as we hurtle towards the Firefox 57 release.

Volume aside, I continue to be impressed with the quality of content emerging…

Smart HTTPS (revived) is the WebExtensions version of one of my favorite yet simple security add-ons—it changes HTTP addresses to the secure HTTPS. Disconnect for Facebook (WebExtension) is another fine privacy tool that prevents Facebook from tracking your Web movement by blocking all Facebook related requests sent between third-party sites.

While we’re talking Facebook, you know what annoys me? Facebook’s “suggested posts” (for some reason I get served a lot of “suggested” content that implies I may have a fatty liver). Kick Facebook Suggested Posts puts an end to that nonsense.

History Cleaner conveniently wipes away your browsing history after a set amount of time, while History Zebra features white and black lists to manage specific sites you want to appear (or not) in your browsing history.

Tab Auto Refresh lets you set timed refresh intervals per tab.

Don’t Touch My Tabs! protects against hyperlinks that try to hijack your previous tab. In other words, when you typically click a link, it grants the new page control over the one you clicked from, which is maybe not-so awesome for a number of reasons, like reloading the page with intrusive ads, or hackers throwing up a fake login to phish your info.

Speaking of tabs, I dig Tab Auto Refresh because I follow a couple of breaking news sites, so with this add-on I set certain tabs to refresh at specific time intervals, then I just click over every so often to catch the latest.

Tabzen is another dynamic tab tool that treats tab management in a familiar bookmarking fashion.

Turn any Reddit page into literally the darkest corner of the Web with dark page themer Reddit Slate Night 2.0 (while we’re on the Reddit tip, this comment collapser presents a compelling alternate layout for perusing conversations).

Dark Mode turns the entire internet goth.

Link Cleaner removes extraneous guck from your URLs, including tracking parameters from commerce sites Amazon and AliExpress.

These are awesome add-ons from very creative developers! It’s great to see such diverse, interesting WebExtensions crop up.

If you’re a developer of a legacy add-on or Chrome extension and want more info about the WebExtensions porting process, this should help. Or if you’re interested in writing a WebExtension from scratch, check this out.

Migrating to WebExtensions? Don’t Forget Your Users

Stranded users feel sadness.

If you’re the developer of a legacy add-on with an aim to migrate to WebExtensions, here are a few tips to consider so your users aren’t left behind.

Port your user data

If your legacy add-on stores user data, we encourage you to take advantage of Embedded WebExtensions to transfer the data to a format that can be used by WebExtensions. This is critical if you want to seamlessly migrate your users—without putting any actionable burden on them—to the new WebExtensions version when it’s ready. (Embedded WebExtensions is a framework that contains your WebExtension inside of a bootstrapped or SDK extension.)

Testing beta versions

If you want to test a WebExtensions version of your add-on with a smaller group of users, you can make use of the beta versions feature on addons.mozilla.org (AMO). This lets you test pre-release beta versions that are signed and available to Firefox users who want to give them a spin. You’ll benefit from real users interacting with your new version and providing valuable feedback—without sacrificing the good reputation and rating of your listed version. We don’t recommend creating a separate listing on release because this will fragment your user base and leave a large number of them behind when Firefox 57 is released.

Don’t leave your users behind

Updating your listing on AMO when your WebExtension is ready is the only way to ensure all of your users move over without any noticeable interruption.

Need further assistance with your migration journey? You can find real-time help during office hours, or by emailing webextensions-support [@] mozilla [dot] org.

Add-ons Update – 2017/03

Here’s the state of the add-ons world this month.

The Road to Firefox 57 explains what developers should look forward to in regards to add-on compatibility for the rest of the year. Please give it a read if you haven’t already.

The Review Queues

In the past month, 1,414 listed add-on submissions were reviewed:

  • 1132 (80%) were reviewed in fewer than 5 days.
  • 31 (2%) were reviewed between 5 and 10 days.
  • 251 (18%) were reviewed after more than 10 days.

There are 594 listed add-ons awaiting review.

We met last week to discuss the state of the queues and our plans to reduce waiting times. There are already some changes coming in the next month or so that should help significantly, but we have larger plans that we will share soon that should address this recurring problem permanently.

If you’re an add-on developer and are looking for contribution opportunities, please consider joining us. Add-on reviewers are critical for our success, and can earn cool gear for their work. Visit our wiki page for more information.

Compatibility

The blog post for 53 is up and the bulk validation will be run soon. Firefox 54 is coming up.

Multiprocess Firefox is enabled for some users, and will be deployed for most users very soon. Make sure you’ve tested your add-on and either use WebExtensions or set the multiprocess compatible flag in your add-on manifest.

As always, we recommend that you test your add-ons on Beta and Firefox Developer Edition to make sure that they continue to work correctly. End users can install the Add-on Compatibility Reporter to identify and report any add-ons that aren’t working anymore.

Recognition

We would like to thank the following people for their recent contributions to the add-ons world:

  • Piotr Drąg
  • Niharika Khanna
  • saintsebastian
  • Atique Ahmed Ziad
  • gilbertginsberg
  • felixgirault
  • StandB
  • lavish205
  • numrut
  • fitojb
  • totaki
  • ingoe

You can read more about their work in our recognition page.

WebExtensions in Firefox 54

Firefox 54 landed in Developer Edition this week, so we have another update on WebExtensions for you. In addition to new APIs to help more developers port over to WebExtensions, we also announced a new Office Hours Support schedule where developers can get more personalized help with the transition.

New APIs

A new API for creating sidebars was implemented. This allows you to place a local HTML file inside the sidebar. The API is similar to the one in Opera. If you specify the sidebar_action manifest key, Firefox will create a sidebar:

To allow keyboard commands to be sent to the sidebar, a new _execute_sidebar_action was added to the commands API which allows you trigger the showing of the sidebar.

The ability to override the about:newtab with pages inside your extension was added to the chrome_url_overrides field in the manifest. Check out the example that uses the topSites API to show the top sites you visit .

The privacy API gives you the ability to flip certain Firefox preferences related to privacy. Although the preferences in Chrome and Firefox aren’t a direct mapping, we’ve mapped the Firefox preferences that makes sense to the APIs. Currently implemented are: networkPredictionEnabled, webRTCIPHandlingPolicy and hyperlinkAuditingEnabled.

The protocol_handler API lets you easily map protocols to actions in your extension. For example: we use irccloud at Mozilla, so we can map ircs:// links to irccloud by adding this into an extension:

  "protocol_handlers": [
    {
      "protocol": "ircs",
      "name": "IRC Mozilla Extension",
      "uriTemplate": "https://irccloud.mozilla.com/#!/%s"
    }
  ]

When a user clicks on an IRC link, it shows the application selector with the IRC Mozilla Extension visible:

This release also marks the landing of the first sets of devtools APIs. Quite a few APIs landed including: inspectedWindow.reload(), inspectedWindow.eval(), inspectedWindow.tabId, network.onNavigated, and panels.create().

Here’s an example of the Redux DevTools extension running on Firefox:

Backwards incompatible changes

The webRequest API will now require that you’ve requested the appropriate hosts’ permissions before allowing you to perform webRequest operations on a URL. This will be a backwards-incompatible change for any extension which used webRequest but did not request the host permission.

Deletes in storage.sync are now encrypted. This would be a breaking change for any extensions using storage.sync on Developer Edition.

API Changes

Some key events were completed in some popular APIs:

  • webRequest.onBeforeRequest is initiated before a server side redirect is about occur and webRequest.onAuthRequired is fired when an authentication failure occurs. These allow you to catch authentication requests from servers, such as proxy authentication.
  • webNavigation.onCreatedNavigationTarget event has been completed. This is fired when a new window or tab is created to be navigated to.
  • runtime.onMessageExternal event has been implemented. This is fired when a message is sent from another extension.

Other notable bugs include:

Android

Notably in Firefox 54, basic tabs API support was landed for Android. The API support focuses on the parts of the API that make sense for Android, so some tab methods and events are deliberately not implemented.

This is an important API in its own right, but other key APIs did not have good support without this. By landing this, Android WebExtensions got much better webNavigation and webRequest support. This gives us a clear path to getting ad blockers, the most common extension type on Android.

Contributors

A big thank you to our contributors Rob Wu, Tomislav Jovanovic and Tushar Saini who helped out with this release.

Improvements to add-on review communications

We recently made some improvements to our tools and processes to better support communication between add-on developers and reviewers.

Previously, when you submitted an add-on to addons.mozilla.org (AMO) and a reviewer emailed you, your replies went to a mailing list (amo-editors AT mozilla DOT org) where a few reviewers (mostly admins) handled every response. This approach had some flaws—it put the burden on very few people to reply, who had to first get familiar with the add-on code and previous review actions. Further replies from either party went to the mailing list only, rather than being fed back into the review tools on AMO. These flaws slowed things down unnecessarily, and contributed to information clutter.

Now, add-on developers can choose to reply to a review by email—like they’re used to—or from the Manage Status & Versions page of the add-on in the developer hub. Replies are picked up by AMO and displayed in the review history for reviewers and developers. In addition, everyone  involved in the review of the particular version will be notified by email. Admin reviewers will make sure all inquiries are followed up with.

This long-anticipated feature will not only make follow-ups for reviews more efficient for both developers and reviewers, it also makes upcoming reviews easier by having all information in the same place.

The mailing list (amo-editors AT mozilla DOT org) will be discontinued shortly, so we ask all developers to use this system instead. For other questions not related to a particular review, please send a message to amo-admins AT mozilla DOT org.

The Add-on Review team would like to thank Andrew Williamson for implementing this new feature and our QA team for testing it!

Office Hours Support for Transitioning and Porting to WebExtensions

To help facilitate more mutual support among developers migrating and porting to WebExtensions, we asked the add-on developer community to sign up for blocks of time when they can be available to assist each other. This week, we published the schedule, which shows you the days and hours (in your time zone) when people are available to answer questions in IRC and the add-on forum. Each volunteer helper has indicated their specialties, so you can find the people who are most likely able to help you.

If you’d like to get help asynchronously, you can join and email the webextensions-support [at] mozilla [dot] org mailing list, where more people are on hand to answer questions.

If you have any knowledge in or expertise with add-ons, please sign up to help! Just go to the etherpad and add your IRC handle, times you’re available, and your specialties, and we’ll add you to the schedule. Or, join the mailing list to help out at any time.

Contribution Opportunity: Mobile Redesign Testing

Calling all testers!

On March 9, a new look will be coming to addons.mozilla.org (AMO) for Android. This redesign will feature a cleaner, more user-friendly add-ons store on Android devices and tablets. We would love your help to track down any remaining bugs.

If you have access to an Android phone and a passion for bug-hunting, we encourage you to look at the instructions on this etherpad and the Contributors Guide and start testing. No prior testing experience is required to contribute. Please be sure to record your name and any bugs you found using the etherpad. After the release on March 9, we still welcome you to file any bugs you see!

If you have any questions or would like to talk to your fellow bug hunters during redesign testing, join the #amo channel at irc.mozilla.org.

Happy testing!

March’s Featured Add-ons

Firefox Logo on blue background

Pick of the Month: Dark YouTube Theme

by NiCU
Watch YouTube clips shrouded in darkness! Try YouTube with a dark periphery instead of the standard bright white.

“Better than I imagined.”

Featured: Turbo Download Manager

by InBasic
A robust multi-threading download manager; includes the option of closing the manager window without interrupting download flow.

“Okay so I’ve been using this downloader about two weeks and it really rocks. The speed is way better than the default downloader and I love how simple it is.”

Featured: Web Clipper: Easy Screenshot

by Jeremy Schomery
Super simple but effective screenshot extension. One click and the context menu offers multiple options, like capturing the entire page, just the visible area, or a selected portion.

“So light, simple, and perfect without useless frills.”

Featured: Clean Uninstall

by rNeomy
Automatically purge obsolete preferences (in pref.js) for add-ons you’ve uninstalled.

“This makes add-on management super clean!”

Featured: To Google Translate

by Juan Escobar
With a couple of clicks you can translate any text via Google Translate.

“برنامج جيد ولاكن ارجو من مطوري البرامج والاضافات كتابة تفاصيل البرامج بالغة العربية اسوتا بالغات الاخرى.”

Nominate your favorite add-ons

Featured add-ons are selected by a community board made up of add-on developers, users, and fans. Board members change every six months. Here’s further information on AMO’s featured content policies.

If you’d like to nominate an add-on for featuring, please send it to amo-featured [at] mozilla [dot] org for the board’s consideration. We welcome you to submit your own add-on!

Add-on Compatibility for Firefox 53

If you haven’t yet, please read our roadmap to Firefox 57. Firefox 53 is an important milestone, when we will stop accepting new legacy add-ons on AMO, will turn Multiprocess Firefox on by default, and will be restricting binary access from add-ons outside of the WebExtensions API.

Firefox 53 will be released on April 18th. Here’s the list of changes that went into this version that can affect add-on compatibility. There is more information available in Firefox 53 for Developers, so you should also give it a look.

General

Password Manager

The 3 following changes are related, and the main impact is that add-ons can no longer call findSlotByName("") to figure out if the master password is set. You can find an example on how to change this here.

XPCOM and Modules

WebExtensions

  • Encrypt record deletes. The storage.sync API hasn’t shipped yet, but it’s probably already in use by some pre-release users. This change causes old synced data to be lost.

Let me know in the comments if there’s anything missing or incorrect on these lists. If your add-on breaks on Firefox 53, I’d like to know.

The automatic compatibility validation and upgrade for add-ons on AMO will happen in a few weeks, so keep an eye on your email if you have an add-on listed on our site with its compatibility set to Firefox 52.