Responsible First-run Usage

Assortment of first-run pages
Extension first-run pages are increasingly common and are a great way to inform the user about what the extension they just installed can do, how to access it, how to get help, and oftentimes guide the user through creating an account or logging in to a service. They are usually very graphical and clean-looking, and really show off the extension or author’s brand. Sometimes in addition to or in lieu of a first-run website in a new tab, additional first-run components are used, such as opening a sidebar or popping up a modal dialog or wizard.

The practice of using first-run modal dialogs, pages, sidebars, and wizards is a great way to make sure the user doesn’t forget to try out your extension after installing it. But there’s a pretty big problem that’s developing as more and more extensions do this: installing more than one extension at a time. As an example, I installed 4 extensions that are “recommended” by Mozilla in a brand new Firefox 3 profile. This is what I got after restarting:

Screenshot of Firefox after first run after extension installs

That’s a pretty horrible sight even if you’re a confident add-on user. Now imagine yourself as a user trying an add-on for the first time, going to the add-ons site and installing a number of extensions that are featured on the home page. It gets worse: after you restart and see what’s in the above screenshot, close the Add-ons Manager and click OK on the modal dialog to see 3 new first-run pages opened, a wizard come up, and another modal dialog come up inside that wizard from a completely different extension but with no way of knowing it’s not related to the wizard extension:

Screenshot of Firefox after first run after extension installs

As a novice add-on user, my first question is “how do I get rid of these windows?”, and my second question is “how do I get rid of these add-ons?”. It gets even worse. After clicking Cancel on all these dialogs, the wizard and its unrelated modal dialog and sidebar will come up every time you start Firefox until they have gotten the attention they demand. Perhaps fortunately in this scenario, novice add-on users aren’t likely to install 4 add-ons at once before restarting. Yet.

One of the most requested features for is add-on bundles and/or shopping cart functionality. The idea behind a “shopping cart” is that you browse around the site, add add-ons to your cart that you want to try out, and do the installation all at once. Or perhaps there’s a pre-made bundle of a few of consumer-friendly add-ons available for me to try out. When all of those are installed at once, I get the above result, even as an add-on beginner.

How do we fix this?

David Rolnitzky, Basil Hashem, a few others, and myself have been discussing this for some time. We have come to the conclusion that there’s no good solution to solve this from the side. Warning the user that the add-ons they’ve selected might conflict is not a good first impression for someone that’s never tried add-ons before, and may justify fears they already have about add-ons being made by third-parties. I’m making this post to ask add-on developers, especially those that are “consumer friendly” to please be as courteous as possible in the first-run experience after a user installs your extension. How do you do this?

  • No first-run modal dialogs! If your extension requires an account login or other settings to be configured immediately, place these forms and elements in your first-run page, an area linked from your first-run page, or in a dialog that is only opened from a control on your first-run page. You may want to make sure your first-run page is in chrome:// if the data is sensitive or requires chrome privileges to be stored.
  • Only one first-run element is needed. If you have a first-run page, you shouldn’t need to use a wizard, dialog, or sidebar too. Instead, use the first-run page to teach the user how to access the extension and allow setup of the extension right from that page.
  • Standardize first-run page usage. Right now, this just means not doing anything particularly crazy or performance-degrading with your first-run page. I recently filed bug 459965 on adding a property to install.rdf that would make adding a first-run page to an extension as simple as typing in the URL to use, which will help make sure the first-run experience plays nicely for all extensions and could even be disabled if the user wanted.

If you’re an extension developer and know that your extension will make a user run away at first-run, please look into ways of improving the first-run experience. If you have a popular extension that does this, I may be contacting you soon to try working out these issues, as the success of package installs and bundling depends on a great user experience.

  • Aaron Strontsman

    Obviously the best solution would be add-on installation that doesn’t require a browser restart. (I know this runs into technical difficulties. And the ideas outlined here aren’t bad, either. Just incomplete.)

  • @Aaron – that’s a completely different topic that would present problems of its own, even if it were doable in the near future (which, given the structure of the platform, it’s not.) Installing multiple add-ons at once, for example, a bundle of consumer friendly add-ons, would still all pop-up their first-run dialogs and windows regardless of whether a restart is required, and nothing is solved.

  • Well, it is a problem. Adblock Plus opens a dialog on first run to allow users select a filter subscription from a list of suggestions. Not doing that would mean that many users will never discover filter subscriptions (and those are also the users who need them most). This dialog isn’t modal – which is good because it isn’t blocking the user, but it is also bad because it will open in background in some cases (in particular in Firefox 3 due to the new add-on notification). It seems that the best (most user-friendly) solution is to open a new tab with a chrome:// URL to show that selection – guess that’s what I will do now.

  • What about a setup-like UI in a tab for all extensions? e.g. I’m writing an extension that requires some kind of user intervention to be setup properly upon first run. All right: I inform the platform (fx, tb, whatever) that upon restart I’ll need to show the user one (or more) pages. The platform, after restarting, instead of the default tab (or alongside it, just like the firefox first run page) shows the page(s) the extension(s) asked to show, with the typical multi-page setup buttons (back, next, cancel). If you hit cancel (or otherwise close the tab), the same tab should appear upon the next restart. Clean, user-firendly, and developers should have no problems at all with that.

  • I kind of think that add-ons shouldn’t do much on the initial startup, providing they add some easy way in the UI to get to them. After I’ve installed an add-on then likely I’ll know to look for it. What I think it a good idea might be if an add-on displayed a notification (alerts service or such) after maybe 10 minutes of usage of Firefox if the user still hasn’t configured things that are really necessary. Gives the user a non-modal reminder that the add-on is there and wants something done.

  • Yeah, that’s kind of a mess.

    One contributing factor might be that it’s a bit tricky to open a tab for a firstrun page, because sessionrestore will clobber any preexisting tabs when it runs… You can listen for a sessionstore-windows-restored notification, but it’s a bit of a lie (it fires a bit too early), so you have to delay creating a page a bit more with a setTimeout. Authors might be hitting these issues and finding that it’s easier to open a new window/prompt instead. I ran into this when writing the Geode extension for Labs.

  • @dolske – Yeah, I imagined there were problems with extensions using different methods of opening a first-run pages, which is why a standardized install.rdf property will help with that tremendously. Good to have a specific example of a problem though – I’ll post in the bug.

  • (In case anyone’s wondering, my issue is bug 460334. Forgot to file it before, this post reminded me!)

  • Ben

    @Justin Dolske — might it be useful to update the MDC docs at to explain the caveat? How much is “a bit too early”?

  • Note that the real fun about opening a new tab on startup starts when you have to support multiple applications (SeaMonkey, Songbird).

  • Mockup time: (first page) (configuration pages)
    hadn’t had the time to do the last page (it should look like the first one, but say something like “congratulations, you did it! you can change the settings anytime from tools > addons”

  • We can’t prevent authors running their own firstrun voodoo, but if we provided them with an alternative then I think that their numbers would decline. I’m thinking something like a little widget, for example in the statusbar, that appears after an add-on is installed. You could choose to overlay a menuitem in there that when selected runs your firstrun bits. It would not go away until done, but that shouldn’t be an issue if it is discreet.

    I’ve also never liked the Add-ons window opening after a new install. That experience could definitely be improved. The new install is commonly not even in view, and the visual clue is not obvious on some platforms/themes.

  • Manish Singh

    Given some viable alternative for extension authors to use, I think it would be fair to reject extensions during review on AMO for putting up dialogs like that.

  • In Firefox, I’ve always liked the clean (imo) approach of opening a new chrome:// tab. But, as Wladimir points out, this won’t work for all Mozilla based applications.

    An install.rdf tag for firstrunURL might be a way to get around the problems Dolske points out as well. It also allows the extension system to control the process better than we can today.

    Allowing the application to “override” the firstrun launch (new tab in Firefox, something else in Fennec) while having a built-in, default display method seems like a good start.

  • @Manish: I thought the same thing. AMO has a lot of leverage there.

    @Fligtar: Well written, thank you. Nothing is more sure to turn a new user away than a “slap in the face” first-run experience. Despite the developers’ best intentions in this case.

  • Yes, having the first-run page defined in install.rdf would be good, also because the application can decide on the best way to deal with it. However, it will take a while until AMO can make using that possibility a hard requirement – until all applications catch up (I am looking specifically at SeaMonkey here) and until support for old application versions can be dropped. So it would help a lot to make this feature detectable so that extensions could use install.rdf and fall back to their own solution for old applications. Bonus points for providing generic fallback code on MDC and recommending it via AMO.

  • I am done implementing this in Adblock Plus. Somehow I didn’t find any use for session restore notifications, the behaviour I see now seems acceptable even without them. What I have now:

    * Browser overlay, code executes on load
    * Global flag (in an XPCOM component) is being set to make sure the first-run code only runs once
    * Retrieves element and calls |browser.selectedTab = browser.addTab(url);|
    * If there is no (Thunderbird, Prism), a dialog is opened

    The result is a little strange in Firefox 3.1 – session restore tab is opened and then my first-run tab. But that isn’t really wrong either.

  • Argh, yet another blog eating XML tags in comments…

    * Browser overlay, code executes on load
    * Global flag (in an XPCOM component) is being set to make sure the first-run code only runs once
    * Retrieves <tabbrowser> element and calls |browser.selectedTab = browser.addTab(url);|
    * If there is no <tabbrowser> (Thunderbird, Prism), a dialog is opened

  • Pingback: Oxymoronical » Blog Archive » Improving the add-on install experience()