Extension API Proposal: action.onUserSettingsChanged

Background

Proposal based on issue #346: New API: UserSettings.isOnToolbar change event

API Overview

Objective

Fire an event when user-specified settings relating to an extension's action changed.

Use Cases

Pinning / unpinning extension

Extensions can know if its action is pinned by calling chrome.action.getUserSettings. If the extension wants to know when this value changes, it has to poll the API method. Instead, it could register for an event.

Implementation

API Schema

Types

dictionary UserSettingsChange {
  isOnToolbar?: boolean
}

Events

// Fires when user-specified settings relating to an extension's action changed.
<browser>.action.onUserSettingsChanged.addListener(
  callback: function, // where callback contains the user site setting changed: (change: UserSettingsChange) => void
);

// Deregisters the event listener.
<browser>.action.onUserSettingsChanged.removeListener(
  callback: function, // where callback looks like: () => void
);

New Permissions

Permission Added	Proposed Warning
N/A	This is an addition to the action API, which is exposed if the extension includes the "action" key in the manifest.

Design and Implementation

Currently, UserSettings only has one property. This makes things easy, as we just need to trigger the event when such property changes. If new properties are added, we will trigger the event every time any of the properties change and return an object with the modified values.

Other Alternatives Considered

Provide both newValue and oldValue in the change event so extension’s event handler can be (more) stateless. However, we decided to go with the alternative selected because:

Given there is only one property and that property is a (never undefined) boolean, that functionally gets us the same benefit as the more broad interface
It more resembles most other APIs events (with the exception of the storage API events)

User Experience

This doesn't introduce any new elements, but does tell the extension an UI element may have changed.

Security and Privacy

This API does not directly expose any sensitive data to the extension.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!