Mozilla's getting a new look. What do you think? https://mzl.la/brandsurvey

Alarme API

This is an experimental technology
Because this technology's specification has not stabilized, check the compatibility table for the proper prefixes to use in various browsers. Also note that the syntax and behavior of an experimental technology is subject to change in future versions of browsers as the spec changes.

Resumo

A API de Alarme provê acesso à configuração de alarmes do dispositivo, com a qual se pode programar notificações ou aplicações para que se iniciem em um momento específico. Porexemplo, algumas aplicações, como o despertador, calendário ou atualizações automáticas utilizam essa API para ativar comportamentos específicos do dispositivo no momento indicado.

Por si só, a API de alarme permite apenas programar os alarmes. Um alarme é enviado para as aplicações através da API de mensagem do sistema, então as aplicações que precisam acionar os alarmes novamente precisam se registrar nas mensagens de alarme.

Os alarmes são estabelecidos usando o objeto window.navigator.mozAlarms que é uma instância de MozAlarmsManager.

Programar Alarmes

A primeira a fazer quando se utiliza o alarme é progrmá-lo. Existem dois tipos de alarme baseados nos fusos-horários. Em ambos os casos é utilizado o método MozAlarmsManager.add.

Nota: Se um alarme não é apontado para uma aplicação específica, o sistema poderá enviá-lo a todas as aplicações que escutam os alarmes.

Alarmes ignorando os fusos-horários

Esse tipo de alarme é enviado baseado na hora do dispositivo. Se o usuário muda o fuso-horário, o alarme será enviado baseado no novo fuso-horário. Por exemplo, se um usuário está em Paris e configura um alarme que deverá ser enviado às 12PM CET (hora da europa central) e o usuário viaja para San Francisco, o alarme será enviado às 12 PM PDT (hora do pacífico).

// Data e hora programada para o alarme
var myDate  = new Date("May 15, 2012 16:20:00");

// Informação passada com o alarme
var data    = {
  foo: "bar"
}

// A string "ignoreTimezone" é o que faz o alarme ignorar isso
var request = navigator.mozAlarms.add(myDate, "ignoreTimezone", data);

request.onsuccess = function () {
  console.log("O alarme foi programado");
};

request.onerror = function () { 
  console.log("Ocorreu um erro: " + this.error.name);
};

Alarmes respeitando os fusos-horários

Esse tipo de alarme é enviado baseado no fuso-horário definido quando o alarme foi programado. Se por alguma razão o usuário do dispositivo mudar seu fuso-horário, o alarme será enviado com base no fuso-horário original. Por exemplo, se um usuário está em Paris e programa um alarme que deveria ser enviado às 12 PM CET (hora da europa central) e se o usuário viaja para San Francisco, o alarme será enviado às 3 AM PDT (hora do pacífico).

// Data e hora do alarme
var myDate  = new Date("May 15, 2012 16:20:00");

// Informação passada com o alarme
var data    = {
  foo: "bar"
}

// A string "honorTimezone" fará com que o alarme respeite o fuso-horário
var request = navigator.mozAlarms.add(myDate, "honorTimezone", data);

request.onsuccess = function () {
  console.log("O alarme foi programado");
};

request.onerror = function () { 
  console.log("Ocorreu um erro: " + this.error.name);
};

Gerenciando os alarmes

Uma vez um alarme é programado, é possível gerenciá-lo.

O método MozAlarmsManager.getAll retornará a lista completa de alarmes atualmente programados pela aplicação.. Essa lista é um Array de objetos mozAlarm.

mozAlarm

São objetos javascript anônimos com as seguintes propriedades:

id
um número represetando o id do alarme
date
um objeto Date representando a hora agendada para o alarme.
respectTimezone
String que indica se o alarme irá respeitar ou ignorar o fuso-horário do objeto date. o valor da string pode ser ignoreTimezone ou honorTimezone
data
um objeto JavaScript contendo uma data que será armazenada com o alarme

var request = navigator.mozAlarms.getAll();

request.onsuccess = function () {
  this.result.forEach(function (alarm) {
    console.log('Id: ' + alarm.id);
    console.log('date: ' + alarm.date);
    console.log('respectTimezone: ' + alarm.respectTimezone);
    console.log('data: ' + JSON.stringify(alarm.data));
  });
};

request.onerror = function () { 
  console.log("An error occurred: " + this.error.name);
};

O método MozAlarmsManager.remove é utilizado para desprogramar um alarme já programado, ou seja, removê-lo.

var alarmId;

// Programa um alarme e obtém o ID do mesmo
var request = navigator.mozAlarms.add(new Date("May 15, 2012 16:20:00"), "honorTimezone");

request.onsuccess = function () {
  alarmId = this.result;
}

// ...

// Remove o alarme se ele existir
if (alarmId) {
  navigator.mozAlarms.remove(alarmId);
}

Manipulação de alarmes

Qualquer aplicação pode ser reativada quando um alarme é programado pelo sistema. Com a finalidade de ser capaz de manipular alarmes, uma aplicação deve ser registrada como manipuladora de alarmes. Isto é feito através da API de mensagens do sistema, em dois passos:

Primeiro, as aplicações deverão incluir alarm na propriedade de mensagens, no manifesto da aplicação, com a URL do documento que registra a função de retorno (callback) que será usada quando o alarme for enviado.

"messages": [
  { "alarm": "/index.html" }
]

Segundo, a aplicação deve linkar a função de retorno com a mensagem de alarm. Isso [e feito utilizando  o método  navigator.mozSetMessageHandler. Essa função receberá o objeto mozAlarm contendo a informação do alarme.

navigator.mozSetMessageHandler("alarm", function (mozAlarm) { 
  alert("alarm fired: " + JSON.stringify(mozAlarm.data)); 
});

Se uma aplicação deseja saber se existe um alarme pendente a nível de sistema, é possível utilizar o método navigator.mozHasPendingMessage com o valor alarm.

navigator.mozHasPendingMessage("alarm"); 

Especificações

Especificação Status Comentário
Web Alarms API Working Draft Especificação inicial.

Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari
Basic support ? 16 (16) moz Não suportado Não suportado Não suportado
Feature Android Chrome for Android Firefox Mobile (Gecko) IE Mobile Opera Mobile Safari Mobile
Basic support ? Não suportado 10.0 (10) moz Não suportado Não suportado Não suportado

Veja mais

Etiquetas do documento e colaboradores

Etiquetas: 
 Colaboradores desta página: jlamim
 Última atualização por: jlamim,