Integrating Add-ons into Firefox

One of the questions I get asked a lot is how to integrate a CCK package into a Firefox distribution or install a CCK into an existing Firefox installation. This post will detail various ways to do that. All of the information I'm about to give applies to all add-ons.

Scenario 1: Include an add-on, prevent users from removing it or disabling it. The user cannot even see the add-on.

To include an add-on in a Firefox distribution and hide it, you need to put it in the distribution/bundles directory. Make a directory called distribution in the same directory where the Firefox executable is located. Next create a subdirectory called bundles. Then create a directory with the same ID as your add-on and unzip it into that directory.

Important Notes: If it is a restartless add-on or an SDK add-on or if the add-on depends on the AddonManager API, this method will NOT work. Also, if your add-on contains search plugins, they have to go in a different directory - distribution/searchplugins/common/. They will not be loaded if they are in your add-on.

Scenario 2: Include an add-on, prevent users from removing it. The user can disable the add-on.

To include an add-on this way, you need to put it in the extensions directory where the Firefox executable is located. Create a directory with the same ID as your add-on and unzip it into that directory. IMPORTANT: If you use this mechanism (which used to work pretty well), your add-ons will be disabled by default. To override this, you'll need to set the preference extensions.autoDisableScopes to 0 via a config file or by creating a new prefs file in the defaults/preferences directory. Setting this value via distribution.ini will not work.

Scenario 3: Install the add-on when a new profile is created. The user can disable or remove the add-on.

For this scenario, we're back to using the distribution directory. The difference will be the directory we place the add-on in. Make a directory called distribution in the same directory where the Firefox executable is located. Next create a subdirectory called extensions. Then create a directory with the same ID as your add-on and unzip it into that directory. Alternatively you can name the XPI with the same ID as your add-on with .XPI on the end and just place the file in that directory.

Important Notes: The add-on is only installed when a new profile is created or when Firefox is being upgraded.

Scenario 4: Install an add-on outside of the Firefox directory, but have it still available in Firefox. The user can disable the add-on.

This scenario covers a lot of different cases. There are various directories on Windows, Mac and Linux where you can install an add-on and it will be picked up by Firefox. You can get more detail on those locations here. A more common option on Windows is to use the registry. Rather than go into detail here, I'll just point to another great article on developer.mozilla.org. IMPORTANT: If you use any of these methods, you run into the extensions.autoDisableScopes problem again. See Scenario 2 for more information.


I've also seen cases where apps locate the profile directory and install an add-on directly into a profile.

Does anyone have any other scenarios that I'm forgetting?

Please note: I reserve the right to delete comments that are offensive or off-topic.

Leave a Reply

Your email address will not be published. Required fields are marked *

69 thoughts on “Integrating Add-ons into Firefox

  1. Is the unzipping of the addons really needed?

    For scenario 3 and the newer FX (>=8.0) I just copied the {add-on-id}.xpi from my profile into the {app-dir}/extensions folder like it was in my {profile-dir}/extensions folder.

    For me this worked fine.

    Yes, I know that there are extensions that need to be unpacked. Just look into your {profile-dir}/extensions folder after a normal install of the add-on.

    Anyway, thanks for the compact info. This keeps my searches short and fruit-full.

    • You bring up a good question. I know in scenario 1, the add-on has to be unpacked.

      If I get some time, I'll check into which scenarios allow packed add-ons and which don't.

      • Scenario 3 is what SeaMonkey uses nowadays for built-in extensions (DOM Inspector, ChatZilla, Venkman, and, in nightlies and hourlies, Debug & QA UI). These extensions are distributed in packed-xpi form in /distribution/extensions/. One small problem is that ChatZilla is moved to the profile without unpacking, which means that when run, it will display a SeaMonkey icon on the taskbar instead of the cZ icon. Otherwise no problem. There would be a problem for the Lightning extension, which doesn't work at all if it isn't unpacked, because it needs access to a timezones database which must not reside inside an xpi archive.

  2. Setting extensions.autoDisableScopes to 0 will mean that *any* 3rd party application will be able to install an addon without asking the user. I'd strongly recommend against altering that preference unless you specifically need all addons in a given scope to be able to be installed and enabled without user consent. If you do need to alter it, only remove the scope that you need to remove - not all of them (ie, don't set it to 0).

    Values are documented here: https://developer.mozilla.org/en/Addons/Add-on_Manager/AddonManager#Installation_scopes
    The values are bit-wise ORed together to give the value of the preference. eg, if you wanted only the application scope to not auto-disable, set extensions.autoDisableScopes to 11.

    • I agree with you for a consumer environment, but not for enterprise environment. These issues have already been discussed on the list.

      The decision to auto disable extensions was problematic for a number of enterprises.

      Most people simply want the behavior to be the same as before Firefox 8. To do that, you set disable scopes to 0.

  3. Ok I am new to this but need some assistance for Mac if anyone can give it to me. I want to integrate mine into the firefox.app but am unsure of the folder structure required. I have tried to follow the instructions but can't seem to get my xpi in the right directory structure. I want it to install for every user when a new profile is created and don't want them to see it or be able to disable it. Any help is a appreciated. I am an IT Specialist at a large school attempting to lock down Firefox.

    • On Mac, the path to the directories I've specified is:

      Firefox.app/Contents/MacOS

      So for your case, it would go in:

      Firefox.app/Contents/MacOS/distribution/bundles/ID OF ADDON

    • Well I had it right, just needed to extract my xpi file and it started to work as expected. Thanks for the input. Now if only I could do the same for Google Chrome to lock it down better. I found some info on it but not making heads or tales about it. Thanks again!

  4. Thanks for a very useful article.

    A have a related question: How can preferences be preset for integrated add-ons?
    I would like to change some add-on default preferences without editing the authors' preferences files.
    I tried adding preferences files ("prefs.js" and "user.js") to the same directories containing the authors' files
    ("%ProgramFiles%\Mozilla Firefox\extensions\{addonID}\defaults\preferences\" for scenario 2;
    "%ProgramFiles%\Mozilla Firefox\distribution\extensions\{addonID}\defaults\preferences\" for scenario 3),
    with mixed and unsatisfactory results.

    What's the secret?

  5. I've created a cutomized FF 10.0.5 ESR installer with a custom extension following Scneario 2. I've also created a scopes-pref.js file and put it in the defaults/pref folder which sets the "extensions.autoDisableScopes" to 0 and the "extensions.enabledScopes" to 15.

    What I'm seeing is that if I install this on a PC with an existing FF installation (3.6.16) the user gets 2 prompts.
    Prompt 1 = "Select Your Add-ons" which shows some extensions saying that they will be disabled unless I check "keep".

    Prompt 2 = "Another program on your computer would like to modify Firefix with the following add-on:" showing the new extension that I'm adding as Scneario 2 as per above.

    How can I get rid of these 2 prompts? After I accept the prompts and look at the about:config, I can see that the scopes settings did indeed get changed as per my js file.

    Thanks

    • To get rid of the first prompt, set this pref:

      extensions.shownSelectionUI

      to true.

      That tells Firefox that dialog was already displayed.

      As far as the second prompt, that one confuses me because you have set extensions.auto.disableScopes correctly.

      I'm hoping the shownSelectionUI resolves it...

      • I added this to my user.js file in core\defaults\pref and that did the trick. Thanks.

        pref("extensions.shownSelectionUI", true);

      • Hello Mike!

        Thanks for your really great blog!

        Our general configuration is:

        Mozilla Firefox\defaults\pref\local-settings.js ->
        Mozilla Firefox\firefox.cfg ->
        https://server.fqdn (autoadmin.global_config_url)

        So far all works but i want to disable these addon tabs.

        pref("extensions.shownSelectionUI", true); // don't ask
        pref("extensions.enabledScopes", 4); // allow managed addons
        pref("extensions.autoDisableScopes", 15); // disable all

        in

        - Mozilla Firefox\defaults\pref\local-settings.js
        - other files (same folder)
        - core\defaults\pref\...
        - Mozilla Firefox\firefox.cfg

        with

        - pref
        - lockPref

        Nothing works.

        Each addon which is new in "Mozilla Firefox\extensions" since last start of Firefox brings up a new tab with:

        "Another program on your computer would like..."

        No ideas anymore. Any help would be greatly appreciated.

        • I am a bit more confused now:

          # in firefox.cfg
          pref("extensions.shownSelectionUI", true);
          pref("extensions.shownSelectionUI", 4);
          pref("extensions.autoDisableScopes", 15);

          ->
          shownSelectionUI+shownSelectionUI go into \prefs.js - autoDisableScopes is missing!

          If i use other files than firefox.cfg: These two settings are missing, too. This occurs even if the settings are in firefox.cfg and in e.g. defaults\prefs\user.js.

          • Sorry - typo (only at your blog) - corrected version:

            I am a bit more confused now:

            # in firefox.cfg
            pref("extensions.shownSelectionUI", true);
            pref("extensions.enabledScopes", 4);
            pref("extensions.autoDisableScopes", 15);

            ->
            shownSelectionUI+enabledScopes go into \prefs.js - autoDisableScopes is missing!

            If i use other files than firefox.cfg: These two settings are missing, too. This occurs even if the settings are in firefox.cfg and in e.g. defaults\prefs\user.js.

          • more precisely:

            the result in the profile folder - prefs.js (extract):

            user_pref("extensions.enabledScopes", 4);
            user_pref("extensions.shownSelectionUI", true);

            extensions.autoDisableScopes is missing but can be found in about:config!

            Reading Mozilla kb:
            "Default varies among versions: Undefined (no disabling, as with 0), 10 (all except app-global and user-profile), 15 (all, but does not apply to some specific locations such as IIUC installdir/extensions/ and profiledir/extensions/)"

            Ah! Firefox 17 ESR has "15" as default. If i try "0" the key/value goes to prefs.js - so the question why the value does not appear in prefs.js is solved.

            Why the tabs appear is still unsolved for me.

          • I tried it in the defaults\preferences folder, too. The settings

            - user_pref("extensions.enabledScopes", 4);
            - user_pref("extensions.shownSelectionUI", true);

            can be seen in about:config but do not prevent the addon manager to come up.

            BTW: I cant reply on your comment... only on mine.

  6. Hello Mike,

    First, Thanks for the great info above.

    Is there a way to inventory all Add-on's and extensions? I would like to see what is add-ons are being used accross the enterprise. Possibly in SCCM? Does that include user profile add-ons?

  7. I'm new to the Firefox special configuration installation process. I searched online endlessly and found the CCK. I then found information related to the unpacking/repacking of the installation files into an installation exe. Cool. I then went through the CCK process to create a specific configuration for a corporate deployment. I have specific settings I'd like to provide in the CCK config. It took me HOURS to scope out and test the preference configurations necessary to include in the xpi. HOURS!!! Ridiculous, I say! There are next to zero resources out there available to provide information on what preferences to select (they're certainly not intuitive) for inclusion in the CCK xpi configuration extension. I managed to somehow find all the ones I needed and confirmed after testing, but then found that a certificate that I added was not being applied. I decided to try creating a separate configuration for that only and including it in the extensions folder. Well.. I ended up finding that this new configuration overwrote my previous one, which included all my preferences that I did not take a screenshot of. I've since tried to "re-find" them but after several hours, I'm still missing 3 settings. Ridiculous!! I've never been so frustrated, in my work life anyway... :-), in all my life. There's VERY few resources out there that provide this information and I'm now at a loss as to where to look.

  8. Hi!
    Very nice article!
    It all seems to work, however addons installed via method 1,2, or 3, act strange. function callbacks fails, component failure, if the addons are in packed form.

    extensions
    addons are added for existing profiles.
    addon updates does not work. and addons are acting strange for example plainoldfavorites. exactly like in distribution/bundles

    distribution/extensions
    works well in unpacked form, but is only added on new firefox profiles. addon updates works.

    distribution/bundles
    (addon updates does not work)
    is added even on existing profile
    will only give me strange errors for example like with plainoldfavorites addon, the dll is not loaded, and the addon does not work. however I can see parts of the addon loaded.

    any idea on how to distribute "plainoldfavorites" via distribution/bundles ?

      • Ah. thanks for clearing that out.
        perhaps there are something more going on with that spesific addon.

        I see this error in firefox esr-17:
        Native module at path 'C:\Programfiler\Mozilla Firefox\extensions\{7E7165E2-0767-448c-852F-5FA8714F2C37}\components\PlainOldFavorites.dll' is incompatible with this version of Firefox, has version 1, expected 17.

        and nightly(week old):
        Native module at path 'C:\Programfiler\Nightly\extensions\{7E7165E2-0767-448c-852F-5FA8714F2C37}\components\PlainOldFavorites.dll' is incompatible with this version of Firefox, has version 1, expected 21.

        And as I said earlier these errors does not show if I use:
        distribution/extensions

        • I have been struggling on the installation of PlainOldFavorites as well. My observation is, that it works as expected when being installed via AddOn-Manager. It will be installed and showing the Favorites Menu in Firefox but this will be showing no entries, when being installed using method 1, 2 and 4 and the same on method 3 for newly created profiles.
          In none of all theese scenarios I could find the .dll Thor names.
          Any hint what else to try for a machine-global functioning installation of that extension for existing as well as for new profiles?

  9. Thank you with your blog I managed to deploy 19 FireFox silently with configuration and extension AdBlock Plus.
    But the extension is not activated at the first start I yet defined pref("extensions.autoDisableScopes", 0);
    pref("extensions.enabledScopes", 15);
    I'm still looking but if you have an idea it is with pleasure
    Excuse me for my bad English

      • I edit the file firefox.js in the firefox.exe \ omni.ja \ defaults \ preferences.
        but I also tried to create a file named user.js in "preferences".
        I'm in a Windows 7 64-bit environment and I deploys with Microsoft SCCM 2012.

        Thank you for your help

  10. Hello Mike!

    Thanks for your really great blog!
    It's really informative.

    I'm trying to set a custom theme as default for firefox. I put the theme folder into distribution/bundles, but didn't work.
    Also, tried under distribution/extensions and found that theme is loaded, but not set active.

    I was wondering, can it be set using default preferences? I can't find any such preference in about:config.

    What I found out that, the only difference when theme is changed is in user's profile, extensions.ini file, [ThemeDirs] attribute changed to new location of theme. So, I put changed file to distribution folder, but it still didn't work.

    • Honestly, I have no idea. I've dont nothing with themes, because I've never had any requests for enterprises to change them.

      • Thanks for your reply.

        I also tried with addon written using addon sdk.
        The distribution/bundles directory doesn't seem to be working with it.

        But, it worked with browser/extensions folder.

        Any possibilities you know if this is expected behavior?

  11. Hi, great utility you have created here and there is a ton of great information.

    Test machine: Windows 7 x64
    I have a question. I think I finally figured out how to integrate the extension into Firefox.
    I created my .xpi from CCK.

    I then created a registry entry for it under:
    HKLM:\SOFTWARE\Wow6432Node\Mozilla\Firefox\Extensions

    Using the registry is the only way I have been able to get Firefox to see my extension.

    I then created the folder under 'C:\Program Files (x86)\Mozilla Firefox\browser\extensions' for my extension with it's ID.

    I created a 'mozilla.cfg' file under 'C:\Program Files (x86)\Mozilla Firefox\'
    I created a 'local-settings.js' under 'C:\Program Files (x86)\Mozilla Firefox\defaults\pref'

    Inside my 'mozilla.cfg' I only have two lines:
    pref("extensions.autoDisableScopes", 0);
    pref("extensions.enabledScopes", 15);

    I did a fresh install of firefox, put all my files in the appropriate places and started firefox and started firefox. I see my extension in the extension list but it is disabled.

    I thought that with the mozilla.cfg config that my extension would get enabled by default but it looks like Firefox is ignoring it.
    I am working with Mozilla Firefox 24.0

    Any suggestions on where I might have gone wrong?

    Thank you,

    Cheers

      • Hi Mike,

        Thank you for taking the time to reply! You have a lot of really great information here. Thank you for taking the time to put it all up for everyone to use.

        I was able to get everything working eventually. I think my installation of Firefox was a little messy so I had done a complete removal and redeployment and that seemed to correct the issue.

        Now the extension is active on first launch and Firefox is fully customized!

        Cheers

  12. Trying to use cck_wizard-1.4-fx to configure Firefox 24ESR. It looks like all the settings are getting applied except for the one that removes the default Mozilla Firefox folder (Help and Tutorial, Customize Firefox, Get Involved and About us) in Customize Bookmarks - Part Two. Any ideas why this is not getting applied?

  13. Hi Mike, your tool is exactly what i've been looking for...and need to use the Scenario #3 above. i've created the .xpi file. My knowledge of adding extensions to Firefox is limited...so if i understand correctly, Firefox installs this directory structure just by default.. (trying to use FF ver. 24 on a Win7 box): C:\Program Files (x86)\Mozilla Firefox\browser\extensions.
    Do i then just need to copy my .xpi file into the extensions folder to have a new users profile have the needed settings from the CCK? mostly i'm trying to set the cert8.db file so all our corporate certs are already there for each user that starts Firefox. Or am i missing some other step? thanks for any help or light you can shed on this.

  14. I am new to Firefox customization. Using ESR 24 and the CCK Wizard. The wizard was intuitive and I have all the settings I want to use for the deployment of Firefox. My confusion comes as to where/what needs to be placed on the users PC to have the changes used.

    • The best place is the distribution/bundles directory as per this post. That makes sure the changes happen, but the user can't disable the add-on.

      • Hi Mike,

        I appreciate all the awesome info you have here! :-) I'm trying to customise the same way as Michele with ESR24 and the CCK Wizard.

        Currently I have:
        C:\Program Files (x86)\Mozilla Firefox\Distribution\Bundles

        With Extension ID:
        {ec8030f7-c20a-464f-9b0e-13a3a9e97384}

        Within there is .xpi and an xpi folder with the sub content.

        This doesn't work unfortunately.

        If I go to Addons and manually open it, it works great. Any ideas why this may not be working, or where I'm going wrong?

        Thanks! :-)

        • For things in distribution/bundles, you just create a directory with any name and unzip the XPI into that directory.

          The XPI should not be there. Not that some add-ons won't work in distribution/bundles though. You would want to check the error console for errors.

  15. hi,

    first of all i wanna thank u for this great article.

    scenario 2 worked for me pretty well with Firefox 17 ESR. I tested now Firefox 25 and it doesnt work anymore. Within the updates of Firefox 17ESR. I had no problems with the setting. With FF25 there are no more addons existing in firefox.

    When i try scenario 3. It works perfectly, but i want the addons to be disabld at the beginning, so the user ist able to choose which addons he wants to activate.

    kind regards

    brainy84

    kind regards

    • Hi,

      I just found your post "http://mike.kaply.com/2013/04/24/major-changes-coming-in-firefox-21/" so i guess my comment is senseless. Sorry for that.

      kind regards

  16. Hi Mike,

    Thanks for information and Is it possible to run a addon in firefox and user cannot see that particular add on is running.

    • Yes, but I generally don't give out that information unless you can tell me exactly why you need to do it.

      It should only be done by a company that has a need to do this.

  17. the downloader keeps downloading certain files into the control panel screen and you cant get rid of them...brilliant.. like flash player and java went there..

  18. How does one *prevent* add-ons from being installed secretly? Is it possible to set Firefox up so that add-ons cannot be installed without the user's knowledge? Thanks.

    • Well, you can block add-on installation completely. Or you can disallow add-ons from specific location on the file system.

      • Occasionally I pick up involuntarily added (read:unwanted) plug-ins. If I knew where they came from, it would be much easier to deal with. The unwanted plugins I can see listed in ff, I can get rid of, but how do I find hidden plugins?

        Once before, I had a serious infection in firefox and luckily Hitman-alert warned me, but I was unable to get rid of it no matter what I did. I tried re-installing ff on top of the existing installation, I tried completely un-installing and re-installing ff, and I even tried two 3rd party removal programs, but the infection persisted. I finally found a solution on-line that worked. It turns out there are several places where files, directories and registry entries must be deleted to completely remove ff. I had to then re-install ff and sync my bookmarks, skip syncing everything else and re-install plugins one by one and re-do my ff settings one by one. What a headache.

        I now have eCleaner 1.4, but I am unsure how to interpret the info it puts out. For example, there is an UNKNOWN ADD-ON:{0C0D0C62-65F4-4280-A611671214C96E56}
        I tried clearing it, but it keeps coming back and I do not know if it is legit or not. How can I find out?

        It seems to me that the root problem is that anyone can install something into ff without my knowledge or consent. I think pale moon is the same, but not sure about tor or comodo dragon. How can I protect myself. Please explain or point me to the information I need. I would be most grateful for your help.

        • So the secret to preventing the loading of add-ons from different places are add-on scopes. See: http://mike.kaply.com/2012/02/21/understanding-add-on-scopes/.

          You can set it so any add-on that's installed at a central location (like the registry) won't be loaded at all. That would be my suggestion. Set extensions.enabledScopes to 1 and then add-ons will only ever be loaded from your profile directory. Definitely read the post for information on the right place to set that preference.

  19. Hi there! Thanks for this great post.
    I think the Scenario 1 is what I am looking for.
    What I have is a 3rd party extension (Symantec add-on installed by the SEP client), that is installed under scope 8 (HKLM registry key). Apparently this cannot be disabled ( as soon as I remove the key, it gets recreated. I am assuming is the SEP Antivirus doing this). What I need to accomplish is enable this for all users and lock it down so they can't disable it.
    My questions:
    1. When choosing scenario 1, how would I be able to see that the extension is actually loaded and installed, since "The user cannot even see the add-on."?
    2. What options would I have to cope with the situation where same add-on is in scope 8 and scope 4 (as I plan to do in order to follow Scenario 1), keeping in mind that my add-on from scope 8 is disabled by default.

    Thanks again,
    Chris

    • To complete my question, what I was thinking of doing was:
      -use lockPref("extensions.enabledScopes",7); to force Firefox to ignore the scope 8 (HKLM registry key) version of the extension
      and then
      -copy the extension to files to C:\Program Files (x86)\Mozilla Firefox\distribution\bundles\{ext_ID}

      I actually did the above, but I cant figure out a way of telling if the extension is actually loaded and enabled... How can I tell this?

      Thank you!

      • You could look for some default preference that is set by the extension. That's the only thing that comes to mind.

        Since extensions in bundles aren't loaded like true extensions, there's no API to check for them.

        • Hi Mike,

          Unfortunately I can't find any preference set by the extension when I look at about:config page. Is there any other way I could tell for sure an extension was loaded when using the Scenario 1?
          Also would you be able to point me in the right direction as to where I could find more info on Scenario 1 onto Mizilla KB or anywhere, I could not find this on another official source...

          Thank you very much!
          Chris.