chrome.alarms

Chrome 120: A partir de Chrome 120, el intervalo mínimo de alarma se redujo de 1 minuto a 30 segundos. Para que se active una alarma en 30 segundos, establece periodInMinutes: 0.5.
Chrome 117: A partir de Chrome 117, la cantidad de alarmas activas se limita a 500. Una vez que se alcance este límite, chrome.alarms.create() fallará. Cuando se usa una devolución de llamada, se establecerá chrome.runtime.lastError. Cuando se usan promesas, estas se rechazan.

Descripción

Usa la API de chrome.alarms para programar el código para que se ejecute de forma periódica o en un momento específico en el futuro.

Permisos

alarms

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

{
  "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 el dispositivo está suspendido. 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ó 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 crea 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 y responder una alarma. Para probar esta API, instala el ejemplo de la API de Alarm desde el repositorio chrome-extension-samples.

Cómo establecer una alarma

En el siguiente ejemplo, se establece una alarma en el trabajador de servicio 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 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),
  });
});

Tipos

Alarm

Propiedades

• nombre

  string

  Es el nombre de esta alarma.

• periodInMinutes

  número opcional

  Si no es nulo, la alarma es una alarma repetitiva y se volverá a activar en periodInMinutes minutos.

• scheduledTime

  número

  Es la hora en la que se programó que se active esta alarma, en milisegundos después de la época (p.ej., Date.now() + n). Por motivos de rendimiento, es posible que la alarma se haya retrasado una cantidad arbitraria más allá de este punto.

AlarmCreateInfo

Propiedades

• delayInMinutes

  número opcional

  Es la cantidad de tiempo, en minutos, después de la cual se debe activar el evento onAlarm.

• periodInMinutes

  número opcional

  Si se configura, el evento onAlarm debe activarse cada periodInMinutes minutos después del evento inicial especificado por when o delayInMinutes. Si no se configura, la alarma solo se activará una vez.

• cuándo

  número opcional

  Es la hora en la que se debe activar la alarma, expresada en milisegundos desde la época (p.ej., Date.now() + n).

Métodos

clear()

Promesa

chrome.alarms.clear(
  name?: string,
  callback?: function,
)

Borra la alarma con el nombre determinado.

Parámetros

• nombre

  cadena opcional

  Es el nombre de la alarma que se borrará. El valor predeterminado es la cadena vacía.

• callback

  función opcional

  El parámetro callback se ve de la siguiente manera:

  (wasCleared: boolean) => void

  • wasCleared

    booleano

Muestra

• Promise<boolean>

  Chrome 91 y versiones posteriores

  Las promesas son compatibles con el manifiesto V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para la retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa se resuelve con el mismo tipo que se pasa a la devolución de llamada.

clearAll()

Promesa

chrome.alarms.clearAll(
  callback?: function,
)

Borra todas las alarmas.

Parámetros

• callback

  función opcional

  El parámetro callback se ve de la siguiente manera:

  (wasCleared: boolean) => void

  • wasCleared

    booleano

Muestra

• Promise<boolean>

  Chrome 91 y versiones posteriores

  Las promesas son compatibles con el manifiesto V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para la retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa se resuelve con el mismo tipo que se pasa a la devolución de llamada.

create()

Promesa

chrome.alarms.create(
  name?: string,
  alarmInfo: AlarmCreateInfo,
  callback?: function,
)

Crea una alarma. Cerca de las horas especificadas por alarmInfo, se activa el evento onAlarm. Si hay otra alarma con el mismo nombre (o sin nombre, si no se especifica ninguno), se cancelará y se reemplazará por esta alarma.

Para reducir la carga en la máquina del usuario, Chrome limita las alarmas a una vez cada 30 segundos como máximo, pero puede retrasarlas una cantidad arbitraria más. Es decir, no se respetará la configuración de delayInMinutes o periodInMinutes en menos de 0.5 y se mostrará una advertencia. when se puede establecer en menos de 30 segundos después de "ahora" sin advertencia, pero no hará que la alarma se active durante al menos 30 segundos.

Para ayudarte a depurar tu app o extensión, cuando la cargas sin descomprimir, no hay límite en la frecuencia con la que se puede activar la alarma.

Parámetros

• nombre

  cadena opcional

  Es un nombre opcional para identificar esta alarma. El valor predeterminado es la cadena vacía.

• alarmInfo

  AlarmCreateInfo

  Describe cuándo se debe activar la alarma. La hora inicial se debe especificar con when o delayInMinutes (pero no con ambos). Si se establece periodInMinutes, la alarma se repetirá cada periodInMinutes minutos después del evento inicial. Si no se configuran when ni delayInMinutes para una alarma recurrente, se usa periodInMinutes como valor predeterminado para delayInMinutes.

• callback

  función opcional

  Chrome 111 y versiones posteriores

  El parámetro callback se ve de la siguiente manera:

  () => void

Muestra

• Promise<void>

  Chrome 111 y versiones posteriores

  Las promesas son compatibles con el manifiesto V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para la retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa se resuelve con el mismo tipo que se pasa a la devolución de llamada.

get()

Promesa

chrome.alarms.get(
  name?: string,
  callback?: function,
)

Recupera detalles sobre la alarma especificada.

Parámetros

• nombre

  cadena opcional

  Es el nombre de la alarma que se debe obtener. El valor predeterminado es la cadena vacía.

• callback

  función opcional

  El parámetro callback se ve de la siguiente manera:

  (alarm?: Alarm) => void

  • alarma

    Alarma opcional

Muestra

• Promise<Alarm | undefined>

  Chrome 91 y versiones posteriores

  Las promesas son compatibles con el manifiesto V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para la retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa se resuelve con el mismo tipo que se pasa a la devolución de llamada.

getAll()

Promesa

chrome.alarms.getAll(
  callback?: function,
)

Obtiene un array de todas las alarmas.

Parámetros

• callback

  función opcional

  El parámetro callback se ve de la siguiente manera:

  (alarms: Alarm[]) => void

  • Alarmas

    Alarm[]

Muestra

• Promise<Alarm[]>

  Chrome 91 y versiones posteriores

  Las promesas son compatibles con el manifiesto V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para la retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa se resuelve con el mismo tipo que se pasa a la devolución de llamada.

Eventos

onAlarm

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

Se activa cuando transcurre una alarma. Es útil para las páginas de eventos.

Parámetros

• callback

  función

  El parámetro callback se ve de la siguiente manera:

  (alarm: Alarm) => void

  • alarma

    Alarma