Alarme API

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.

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

Navegadores compatíveis

Veja mais

• navigator.mozAlarms
• MozAlarmsManager
• window.navigator.mozSetMessageHandler