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 Note: 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.
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?
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.
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.
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!
Thank you!
Scenario 1 works great for me.
And the tipp for Mac is helpfull too.
Regards
Jens
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?
I wouldn't recommend changing extension preferences in the extensions themselves.
If you know the preferences, you can set them as part of the default preference files.
http://mike.kaply.com/2012/03/15/customizing-firefox-default-preference-files/
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.
Just to be clear, these preferences have to go in a file in the defaults/preferences directory, NOT the defaults/prefs directory. Those are two different directories. And they cannot be set via a firefox.cfg.
See:
http://mike.kaply.com/2012/02/21/understanding-add-on-scopes/
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.
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?
Sorry for missing this.
Some pretty simple code could be written to do this. Do you still need this?
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.
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 ?
I've just made a post that covers a little of this.
http://mike.kaply.com/2013/02/11/add-ons-in-the-distribution-directory/
Basically add-ons in the distribution/bundles directory aren't loaded like real add-ons. So some APIs won't work.
It appears that plainoldfavorites is one of those add-ons.
I find it odd that plainoldfavorites doesn't work in extensions, though. That should work.
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?
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
Where are you setting autoDisableScopes and autoEnabledScopes? What file in what location?
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