Updating addons broken by private browsing changes

After reading this document, contact Josh Matthews with further questions or clarifications, or file a bug if your extension has stopped working due to a change described here and you are having trouble updating it.

How do I know if my addon is affected by these changes?

If your code refers to any of the following interfaces:

FF 15:

FF 16:

FF 18:

FF 19:

FF 20:

Furthermore, if your code uses any of these common chrome APIs:

FF 19:

FF 20:

Finally, if your code watches for any of these observer notifications:

Then your addon will require updating to correctly support the new per-window private browser feature in Firefox 20 (and will require updating to work correctly in releases of Firefox since the ones listed).


nsITransferable: See Using the clipboard for information about the new init method.

imgICache: This must no longer be obtained as a service. See the imgICache article for more information.

mozIAsyncFavicons/nsIFaviconService: setAndFetchFaviconForPage/setAndLoadFaviconForPage now take a required privacy status argument, either nsIFaviconService.FAVICON_LOAD_PRIVATE or nsIFaviconService.FAVICON_LOAD_NON_PRIVATE.

nsIWebBrowserPersist: saveURI gained a new argument; see the nsIWebBrowserPersist docs for more information.

nsIContentPrefService: getPref, setPref, hasPref, hasCachedPref, removePref, removeGroupedPrefs, removePrefsByName, getPrefs, and getPrefsByName all take a required nsILoadContext argument to indicate the privacy status of the pref in question. Use PrivateBrowsingUtils.getPrivacyContextFromWindow(win) to obtain it from the relevant window.


  • Integer download IDs (and specifically the id property of nsIDownload) are deprecated, and don't allow access to private downloads. All downloads now use GUIDs, and contain a new guid property.
  • nsIDownload now has retry, cancel, remove, pause, and resume methods which should be used instead of deprecated similarly-named nsIDownloadManager methods.
  • nsIDownload's getDownload method is deprecated; use the asynchronous getDownloadByGUID method instead.
  • nsIDownloadManager now has activePrivateDownloads, activePrivateDownloadCount, and privateDBConnection members to complement the existing public ones.
  • nsIDownloadManager's addListener method is deprecated. addPrivacyAwareListener should be used instead, or no notifications will be received for private downloads.
  • There is a new download-manager-remove-download-guid notification, which passes an nsISupportsCString subject for the GUID or null.

nsIHttpAuthManager: setAuthIdentity and getAuthIdentity now take an optional boolean parameter to indicate whether the identity is classified as private.

nsIStrictTransportSecurityService: processStsHeader, removeStsState, isStsHost, and isStsUri now take a flags parameter that understands nsISocketProvider.NO_PERMANENT_STORAGE or nothing.

nsIPrivateBrowsingService: This service is deprecated, and as of Firefox 20 it is now an empty interface. If your code depends on this interface, it will break. The global private browsing service is actively being removed, and may not even exist as of Firefox 21.

nsIRecentBadCertsService: This is no longer a global service, and has been renamed to nsIRecentBadCerts. To obtain this, acquire the nsIX509CertDB service, and use the new getRecentBadCerts method, passing a boolean indicating whether the private bad certificates or public ones are desired.

Observer notifications

None of the ones listed above will be sent as of Firefox 20. The supporting per-window private browsing article explains further about the equivalent notifications, which are all backwards compatible through to Firefox 12 (and are sent side-by-side with the global private browsing notifications in older versions).

Chrome APIs

OpenBrowserWindow: Takes an optional parameter to indicate desired properties of the window. Passing {private: true} will cause a private window to open, otherwise the window will always be non-private. Use {private: PrivateBrowsingUtils.isWindowPrivate(window)} to open a window that matches the current window's privacy status.

openLinkIn: Can receive an extra private boolean property in the parameter object.

internalSave: Takes a new required Document argument (prior to the optional boolean and string arguments) indicating the document that originated the save action.

gPrivateBrowsingUI: Can no longer be used to control private browsing of any kind. Any new private browsing session should be opened using OpenBrowserWindow, and any queries for private browsing status should use PrivateBrowsingUtils.isWindowPrivate(win) on a relevant window object.

saveURL: Takes a new required Document argument indicating the source of the URL being saved.