chrome.events
Description: |
The chrome.events namespace contains common types used by APIs dispatching events to notify you when something interesting happens.
|
Availability: |
Since Chrome 35.
|
An Event
is an object
that allows you to be notified
when something interesting happens.
Here's an example of using the
chrome.alarms.onAlarm
event
to be notified whenever an alarm has elapsed:
chrome.alarms.onAlarm.addListener(function(alarm) { appendToLog('alarms.onAlarm --' + ' name: ' + alarm.name + ' scheduledTime: ' + alarm.scheduledTime); });
As the example shows,
you register for notification using addListener()
.
The argument to addListener()
is always a function that you define to handle the event,
but the parameters to the function depend on
which event you're handling.
Checking the documentation for
alarms.onAlarm,
you can see that the function has a single parameter:
an alarms.Alarm object
that has details about the elapsed alarm.
Declarative Event Handlers
The declarative event handlers provide a means to define rules consisting of declarative conditions and actions. Conditions are evaluated in the browser rather than the JavaScript engine which reduces roundtrip latencies and allows for very high efficiency.
Declarative event handlers are used for example in the Declarative Web Request API and Declarative Content API. This page describes the underlying concepts of all declarative event handlers.
Rules
The simplest possible rule consists of one or more conditions and one or more actions:
var rule = { conditions: [ /* my conditions */ ], actions: [ /* my actions */ ] };
If any of the conditions is fulfilled, all actions are executed.
In addition to conditions and actions you may give each rule an identifier, which simplifies unregistering previously registered rules, and a priority to define precedences among rules. Priorities are only considered if rules conflict each other or need to be executed in a specific order. Actions are executed in descending order of the priority of their rules.
var rule = { id: "my rule", // optional, will be generated if not set. priority: 100, // optional, defaults to 100. conditions: [ /* my conditions */ ], actions: [ /* my actions */ ] };
Event objects
Event objects may support rules. These event objects don't call a callback function when events happen but test whether any registered rule has at least one fulfilled condition and execute the actions associated with this rule. Event objects supporting the declarative API have three relevant methods: events.Event.addRules, events.Event.removeRules, and events.Event.getRules.
Adding rules
To add rules call the addRules()
function of the event object. It
takes an array of rule instances as its first parameter and a callback function
that is called on completion.
var rule_list = [rule1, rule2, ...]; function addRules(rule_list, function callback(details) {...});
If the rules were inserted successfully, the details
parameter
contains an array of inserted rules appearing in the same order as in the passed
rule_list
where the optional parameters id
and
priority
were filled with the generated values. If any rule is
invalid, e.g., because it contained an invalid condition or action, none of the
rules are added and the
runtime.lastError variable is set when
the callback function is called. Each rule in rule_list
must
contain a unique identifier that is not currently used by another rule or an
empty identifier.
Note: Rules are persistent across browsing sessions. Therefore,
you should install rules during extension installation time using the
runtime.onInstalled
event. Note that this event is also triggered when an extension is updated.
Therefore, you should first clear previously installed rules and then register
new rules.
Removing rules
To remove rules call the removeRules()
function. It accepts an
optional array of rule identifiers as its first parameter and a callback
function as its second parameter.
var rule_ids = ["id1", "id2", ...]; function removeRules(rule_ids, function callback() {...});
If rule_ids
is an array of identifiers, all rules having
identifiers listed in the array are removed. If rule_ids
lists an
identifier, that is unknown, this identifier is silently ignored. If
rule_ids
is undefined
, all registered rules of this
extension are removed. The callback()
function is called when the
rules were removed.
Retrieving rules
To retrieve a list of currently registered rules, call the
getRules()
function. It accepts an optional array of rule
identifiers with the same semantics as removeRules
and a callback
function.
var rule_ids = ["id1", "id2", ...]; function getRules(rule_ids, function callback(details) {...});
The details
parameter passed to the callback()
function
refers to an array of rules including filled optional parameters.
Performance
To achieve maximum performance, you should keep the following guidelines in mind:
Register and unregister rules in bulk. After each registration or unregistration, Chrome needs to update internal data structures. This update is an expensive operation.
Instead of
var rule1 = {...}; var rule2 = {...}; chrome.declarativeWebRequest.onRequest.addRules([rule1]); chrome.declarativeWebRequest.onRequest.addRules([rule2]);
prefer to write
var rule1 = {...}; var rule2 = {...}; chrome.declarativeWebRequest.onRequest.addRules([rule1, rule2]);
- Prefer substring matching over matching using regular expressions in a
events.UrlFilter. Substring based matching is extremely fast.
Instead of
var match = new chrome.declarativeWebRequest.RequestMatcher({ url: {urlMatches: "example.com/[^?]*foo" } });
prefer to write
var match = new chrome.declarativeWebRequest.RequestMatcher({ url: {hostSuffix: "example.com", pathContains: "foo"} });
- If you have many rules that all share the same actions, you may merge
the rules into one because rules trigger their actions as soon as a single
condition is fulfilled. This speeds up the matching and reduces memory
consumption for duplicate action sets.
Instead of
var condition1 = new chrome.declarativeWebRequest.RequestMatcher({ url: { hostSuffix: 'example.com' } }); var condition2 = new chrome.declarativeWebRequest.RequestMatcher({ url: { hostSuffix: 'foobar.com' } }); var rule1 = { conditions: [condition1], actions: [new chrome.declarativeWebRequest.CancelRequest()]}; var rule2 = { conditions: [condition2], actions: [new chrome.declarativeWebRequest.CancelRequest()]}; chrome.declarativeWebRequest.onRequest.addRules([rule1, rule2]);
prefer to write
var rule = { conditions: [condition1, condition2], actions: [new chrome.declarativeWebRequest.CancelRequest()]}; chrome.declarativeWebRequest.onRequest.addRules([rule]);
Filtered events
Filtered events are a mechanism that allows listeners to specify a subset of events that they are interested in. A listener that makes use of a filter won't be invoked for events that don't pass the filter, which makes the listening code more declarative and efficient - an event page page need not be woken up to handle events it doesn't care about.
Filtered events are intended to allow a transition from manual filtering code like this:
chrome.webNavigation.onCommitted.addListener(function(e) { if (hasHostSuffix(e.url, 'google.com') || hasHostSuffix(e.url, 'google.com.au')) { // ... } });
into this:
chrome.webNavigation.onCommitted.addListener(function(e) { // ... }, {url: [{hostSuffix: 'google.com'}, {hostSuffix: 'google.com.au'}]});
Events support specific filters that are meaningful to that event. The list of filters that an event supports will be listed in the documentation for that event in the "filters" section.
When matching URLs (as in the example above), event filters support the same URL matching capabilities as expressible with a events.UrlFilter, except for scheme and port matching.
Summary
Types | |
---|---|
Rule | |
Event | |
UrlFilter |
Types
Rule
properties | ||
---|---|---|
string | (optional) id |
Optional identifier that allows referencing this rule. |
array of string | (optional) tags |
Tags can be used to annotate rules and perform operations on sets of rules. |
array of any | conditions |
List of conditions that can trigger the actions. |
array of any | actions |
List of actions that are triggered if one of the conditions is fulfilled. |
integer | (optional) priority |
Optional priority of this rule. Defaults to 100. |
Event
methods | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
addListener
Event.addListener(function callback)
Registers an event listener callback to an event.
| ||||||||||||
removeListener
Event.removeListener(function callback)
Deregisters an event listener callback from an event.
| ||||||||||||
hasListener
boolean
Event.hasListener(function callback)
| ||||||||||||
hasListeners
boolean
Event.hasListeners()
| ||||||||||||
addRules
Event.addRules(array of Rule rules, function callback)
Registers rules to handle events.
| ||||||||||||
getRules
Event.getRules(array of string ruleIdentifiers, function callback)
Returns currently registered rules.
| ||||||||||||
removeRules
Event.removeRules(array of string ruleIdentifiers, function callback)
Unregisters currently registered rules.
|
UrlFilter
properties | ||
---|---|---|
string | (optional) hostContains |
Matches if the host name of the URL contains a specified string. To test whether a host name component has a prefix 'foo', use hostContains: '.foo'. This matches 'www.foobar.com' and 'foo.com', because an implicit dot is added at the beginning of the host name. Similarly, hostContains can be used to match against component suffix ('foo.') and to exactly match against components ('.foo.'). Suffix- and exact-matching for the last components need to be done separately using hostSuffix, because no implicit dot is added at the end of the host name. |
string | (optional) hostEquals |
Matches if the host name of the URL is equal to a specified string. |
string | (optional) hostPrefix |
Matches if the host name of the URL starts with a specified string. |
string | (optional) hostSuffix |
Matches if the host name of the URL ends with a specified string. |
string | (optional) pathContains |
Matches if the path segment of the URL contains a specified string. |
string | (optional) pathEquals |
Matches if the path segment of the URL is equal to a specified string. |
string | (optional) pathPrefix |
Matches if the path segment of the URL starts with a specified string. |
string | (optional) pathSuffix |
Matches if the path segment of the URL ends with a specified string. |
string | (optional) queryContains |
Matches if the query segment of the URL contains a specified string. |
string | (optional) queryEquals |
Matches if the query segment of the URL is equal to a specified string. |
string | (optional) queryPrefix |
Matches if the query segment of the URL starts with a specified string. |
string | (optional) querySuffix |
Matches if the query segment of the URL ends with a specified string. |
string | (optional) urlContains |
Matches if the URL (without fragment identifier) contains a specified string. Port numbers are stripped from the URL if they match the default port number. |
string | (optional) urlEquals |
Matches if the URL (without fragment identifier) is equal to a specified string. Port numbers are stripped from the URL if they match the default port number. |
string | (optional) urlMatches |
Matches if the URL (without fragment identifier) matches a specified regular expression. Port numbers are stripped from the URL if they match the default port number. The regular expressions use the RE2 syntax. |
string | (optional) originAndPathMatches |
Matches if the URL without query segment and fragment identifier matches a specified regular expression. Port numbers are stripped from the URL if they match the default port number. The regular expressions use the RE2 syntax. |
string | (optional) urlPrefix |
Matches if the URL (without fragment identifier) starts with a specified string. Port numbers are stripped from the URL if they match the default port number. |
string | (optional) urlSuffix |
Matches if the URL (without fragment identifier) ends with a specified string. Port numbers are stripped from the URL if they match the default port number. |
array of string | (optional) schemes |
Matches if the scheme of the URL is equal to any of the schemes specified in the array. |
array of integer or array of integer | (optional) ports |
Matches if the port of the URL is contained in any of the specified port lists. For example |