Google Chrome Extensions

chrome.alarms

API Reference: chrome.alarms

Types

Alarm

( object )

Properties of Alarm

periodInMinutes ( optional double )
If not null, the alarm is a repeating alarm and will fire again in periodInMinutes minutes.
scheduledTime ( double )
Time at which this alarm was scheduled to fire, in milliseconds past the epoch (e.g. Date.now() + n). For performance reasons, the alarm may have been delayed an arbitrary amount beyond this.
name ( string )
Name of this alarm.

AlarmCreateInfo

( object )

Properties of AlarmCreateInfo

delayInMinutes ( optional double )
Length of time in minutes after which the onAlarm event should fire.

periodInMinutes ( optional double )
If set, the onAlarm event should fire every periodInMinutes minutes after the initial event specified by when or delayInMinutes. If not set, the alarm will only fire once.

when ( optional double )
Time at which the alarm should fire, in milliseconds past the epoch (e.g. Date.now() + n).

Methods

create

chrome.alarms.create(string name, AlarmCreateInfo alarmInfo)

Creates an alarm. Near the time(s) specified by alarmInfo, the onAlarm event is fired. If there is another alarm with the same name (or no name if none is specified), it will be cancelled and replaced by this alarm.

Note that granularity is not guaranteed: times are more of a hint to the browser. For performance reasons, alarms may be delayed an arbitrary amount of time before firing.

Parameters

name ( optional string )
Optional name to identify this alarm. Defaults to the empty string.
alarmInfo ( AlarmCreateInfo )
Describes when the alarm should fire. The initial time must be specified by either when or delayInMinutes (but not both). If periodInMinutes is set, the alarm will repeat every periodInMinutes minutes after the initial event. If neither when or delayInMinutes is set for a repeating alarm, periodInMinutes is used as the default for delayInMinutes.

get

chrome.alarms.get(string name)

Retrieves details about the specified alarm.

Parameters

name ( optional string )
The name of the alarm to get. Defaults to the empty string.

Callback function

The callback parameter should specify a function that looks like this:

function(Alarm alarm) {...};
alarm ( Alarm )

getAll

chrome.alarms.getAll()

Gets an array of all the alarms.

clear

chrome.alarms.clear(string name)

Clears the alarm with the given name.

Parameters

name ( optional string )
The name of the alarm to clear. Defaults to the empty string.

clearAll

chrome.alarms.clearAll()

Clears all alarms.

Events

onAlarm

chrome.alarms.onAlarm.addListener(function(Alarm alarm) {...});

Fired when an alarm has elapsed. Useful for event pages.

Listener Parameters

alarm ( Alarm )
The alarm that has elapsed.

Sample Extensions that use chrome.alarms

  • Event Page Example – Demonstrates usage and features of the event page
  • Google Mail Checker – Displays the number of unread messages in your Google Mail inbox. You can also click the button to open your inbox.