chrome.alarms

Descripción

Permisos

Para usar la API de chrome.alarms, declara el permiso "alarms" en el manifiesto:

{
  "name": "My extension",
  ...
  "permissions": [
    "alarms"
  ],
  ...
}

Conceptos y uso

Para garantizar un comportamiento confiable, es útil comprender cómo se comporta la API.

Suspensión del dispositivo

Las alarmas siguen ejecutándose mientras un dispositivo está en suspensión. Sin embargo, una alarma no activará un dispositivo. Cuando el dispositivo se active, se activarán todas las alarmas perdidas. Las alarmas repetidas se activarán como máximo una vez y, luego, se reprogramarán con el período especificado a partir de cuando se active el dispositivo, sin tener en cuenta el tiempo que ya transcurrió desde que se configuró originalmente la alarma para que se ejecutara.

Persistencia

Puedes controlar la persistencia de una alarma en el momento de la creación con la persistAcrossSessions marca. Se puede establecer en true (persiste hasta que se actualiza la extensión) o false (se borra si se vuelve a cargar la extensión o se reinicia el navegador, y cada vez que se actualiza la extensión).

Otros navegadores y versiones anteriores de Chrome

Esta propiedad no es compatible con otros navegadores (problema) ni con versiones de Chrome anteriores a Chrome 150, en las que el comportamiento puede ser impredecible. Por lo tanto, es mejor asegurarse de que existan alarmas importantes cada vez que se inicie tu service worker. Por ejemplo:

async function checkAlarmState() {
  const alarm = await chrome.alarms.get("my-alarm");

  if (!alarm) {
    await chrome.alarms.create("my-alarm", { periodInMinutes: 1 });
  }
}

checkAlarmState();

Si tu alarma se crea de forma dinámica en función de la acción del usuario, es posible que desees almacenar que se creó una alarma en otro lugar para saber cómo volver a crearla si es necesario.

Ejemplos

En los siguientes ejemplos, se muestra cómo usar una alarma y responder a ella. Para probar esta API, instala el ejemplo de la API de Alarm del repositorio chrome-extension-samples.

Cómo establecer una alarma

En el siguiente ejemplo, se establece una alarma en el service worker cuando se instala una versión nueva de la extensión:

service-worker.js:

chrome.runtime.onInstalled.addListener(async ({ reason }) => {
  // Create an alarm so we have something to look at in the demo
  await chrome.alarms.create('demo-default-alarm', {
    delayInMinutes: 1,
    periodInMinutes: 1,
    persistAcrossSessions: true
  });
});

Cómo responder a una alarma

En el siguiente ejemplo, se establece el ícono de la barra de herramientas de acción según el nombre de la alarma que se activó.

service-worker.js:

chrome.alarms.onAlarm.addListener((alarm) => {
  chrome.action.setIcon({
    path: getIconPath(alarm.name),
  });
});

chrome.alarms.clear(
  name?: string,
): Promise<boolean>

chrome.alarms.clearAll(): Promise<boolean>

chrome.alarms.create(
  name?: string,
  alarmInfo: AlarmCreateInfo,
): Promise<void>

chrome.alarms.get(
  name?: string,
): Promise<Alarm | undefined>

chrome.alarms.getAll(): Promise<Alarm[]>

chrome.alarms.onAlarm.addListener(
  callback: function,
)