cookies.onChanged

The onChanged event of the {{WebExtAPIRef("cookies")}} API fires when a cookie that the extension can access is set or removed.

[!NOTE] When storage partitioning is active, cookies.Cookie.partitionKey contains the description of the cookie's storage partition. When modifying cookies, it's important to pass this value to {{WebExtAPIRef("cookies.set()")}} or {{WebExtAPIRef("cookies.remove()")}} to ensure the extension works with the correct cookie.

Note that updating a cookie's properties is implemented as a two step process:

1. First, the cookie to be updated is first removed, generating a notification with a {{WebExtAPIRef("cookies.OnChangedCause")}} of overwrite.
2. Next, a new cookie is written with the updated values, generating a second notification with a {{WebExtAPIRef("cookies.OnChangedCause")}} of explicit.

Syntax

browser.cookies.onChanged.addListener(listener)
browser.cookies.onChanged.removeListener(listener)
browser.cookies.onChanged.hasListener(listener)

This API is also available as browser.cookies.onChanged.*.

Events have three functions:

• addListener(listener)
  • : Adds a listener to this event.
• removeListener(listener)
  • : Stops listening to this event. The listener argument is the listener to remove.
• hasListener(listener)
  • : Checks whether listener is registered for this event. Returns true if it is listening, false otherwise.

addListener syntax

Parameters

• listener
  • : The function called when this event occurs. The function is passed these arguments:
    • changeInfo
      • : An object containing details of the change that occurred. Its properties are:
        • removed
          • : A boolean set to true if a cookie was removed and false if not.
        • cookie
          • : A {{WebExtAPIRef('cookies.Cookie')}} object containing information about the cookie that was set or removed.
        • cause
          • : A {{WebExtAPIRef('cookies.OnChangedCause')}} value representing the underlying reason behind the cookie's change.

Examples

This example listens for onChanged events and logs details from the changeInfo argument:

browser.cookies.onChanged.addListener((changeInfo) => {
  console.log(
    `Cookie changed: \n` +
      ` * Cookie: ${JSON.stringify(changeInfo.cookie)}\n` +
      ` * Cause: ${changeInfo.cause}\n` +
      ` * Removed: ${changeInfo.removed}`,
  );
});

{{WebExtExamples}}

Browser compatibility

{{Compat}}

[!NOTE] This API is based on Chromium's chrome.cookies API. This documentation is derived from cookies.json in the Chromium code.