Labs/Jetpack/Reboot/JEP/116

JEP 116 - Private Browsing

• Champion: Ehsan Akhgari - ehsan@mozilla.com
• Status: Under Review
• Bug Ticket:
• Type: API
• Difficulty: 1

Proposal

This JEP describes an API for querying the current private browsing mode status, and responding to its changes. In particular, it gives a Jetpack a property for getting the current status of the private browsing mode and entering or leaving the private browsing mode, and for registering event handlers for getting notified about private browsing mode transitions, and canceling them if needed.

Properties

This JEP provides the active property which allows Jetpacks to query the current status of the private browsing mode. If the private browsing mode is active, the value of the active property will be false, otherwise it will be true.

var pb = require("private-browsing");

var insidePB = pb.active;

if (insidePB) {
  // We're inside the private browsing mode
} else {
  // Private browsing is not activated
}

Jetpacks can also set the active property to change the current status of the private browsing mode. Setting this property to true will tell Firefox to enter the private browsing mode, and setting it to false will tell Firefox to leave the private browsing mode. Setting this property to its current value doesn't have any effect.

var pb = require("private-browsing");

// Enter the private browsing mode
pb.active = true;

// Do something...

// Leave the private browsing mode
pb.active = false;

Events

The events are used for Jetpacks which want to respond to changes made to the private browsing status by the user or other Jetpacks/extensions.

The first class of event handlers are used to notify Jetpacks about changes in the global private browsing status. These event handlers can be used like this:

var pb = require("private-browsing");

pb.onActivate = function() {
  // Oh, the private browsing mode has just started!
};

pb.onDeactivate = function() {
  // The private browsing mode just ended!
};

Some Jetpacks may need to cancel the transition of the private browsing mode in certain cases. Such Jetpacks can use the following event handlers. The activation or deactivation of the private browsing mode will be canceled only if these event handlers explicitly cancel the event. It should be noted that if another Jetpack or extension also implements these event handlers and cancels a transition, the event handler on the remaining Jetpacks will not be called.

var pb = require("private-browsing");

pb.onBeforeActivate = function(pb) {
  // We don't want to allow entering the private browsing mode.
  pb.cancel();
};

pb.onBeforeDeactivate = function(pb) {
  // We don't want to allow leaving the private browsing mode.
  pb.cancel();
};

Difficulty

Rating: Easy

Key Issues

None so far!

Dependencies & Requirements

This JEP is not dependent on any other JEPs.

Internal Methods

The JEP will be implemented in terms of nsIPrivateBrowsingService for implementation of the active property, and nsIObserverService for implementation of event handlers.

Use Cases

• Provide a different appearance for the Jetpack when the private browsing mode is active.
• Avoid writing data containing the web page URLs and domains that the user has visited inside the private browsing mode.
• Prevent the transition of the private browsing mode if a non-resumable and non-cancelable operation is in progress.