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 sonando mientras el dispositivo está en suspensión. Sin embargo, una alarma no activará un dispositivo. Cuando el dispositivo se active, se activarán las alarmas perdidas. Las alarmas repetitivas se activarán como máximo una vez y, luego, se reprogramarán con el período especificado a partir del momento en que 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

Por lo general, las alarmas persisten hasta que se actualiza una extensión. Sin embargo, esto no está garantizado, y es posible que las alarmas se borren cuando se reinicie el navegador. Por lo tanto, considera establecer un valor en el almacenamiento cuando se cree una alarma y, luego, asegúrate de que exista cada vez que se inicie tu service worker. Por ejemplo:

const STORAGE_KEY = "user-preference-alarm-enabled";

async function checkAlarmState() {
  const { alarmEnabled } = await chrome.storage.get(STORAGE_KEY);

  if (alarmEnabled) {
    const alarm = await chrome.alarms.get("my-alarm");

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

checkAlarmState();

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 desde el repositorio de chrome-extension-samples.

Cómo establecer una alarma

En el siguiente ejemplo, se configura una alarma en el service worker cuando se instala la extensión:

service-worker.js:

chrome.runtime.onInstalled.addListener(async ({ reason }) => {
  if (reason !== 'install') {
    return;
  }

  // Create an alarm so we have something to look at in the demo
  await chrome.alarms.create('demo-default-alarm', {
    delayInMinutes: 1,
    periodInMinutes: 1
  });
});

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 sonó.

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,
)