Alarm API

Cette traduction est incomplète. Aidez à traduire cet article depuis l'anglais.

Cette fonction est expérimentale
Puisque cette fonction est toujours en développement dans certains navigateurs, veuillez consulter le tableau de compatibilité pour les préfixes à utiliser selon les navigateurs.
Il convient de noter qu'une fonctionnalité expérimentale peut voir sa syntaxe ou son comportement modifié dans le futur en fonction des évolutions de la spécification.

Résumé

L'API Alarm permet d'accéder aux paramètres d'alarme de l'appareil, qui peuvent planifier une notification ou le lancement d'une application à un moment précis. Par exemple, certaines applications comme le radio-réveil, le calendrier ou ou encore la mise à jour automatique peuvent devoir utiliser l'API Alarm pour déclencher des comportements de périphérique particulier à des moments spécifiés.

En soi, l'API Alarm permet seulement de programmer des alarmes. Une alarme est distribuée aux applications via l'API de Message système, ainsi les applications qui veulent réagir aux alarmes doivent s'inscrire elles-mêmes aux messages d'alarm.
 

Les alarmes sont réglées en utilisant l'objet window.navigator.mozAlarms qui est une instance de l'interface MozAlarmsManager.

Programmer des alarmes

Les premières choses à faire lors de l'utilisation d'Alarm sont de programmer des alarmes. Il y a deux types d'alarmes fondées sur le respect des fuseaux horaires. Dans les deux cas,  ceci est fait à l'aide de la méthode MozAlarmsManager.add .
 

Remarque : Si une alarme n'est pas destinée à une application spécifique, le système enverra toutes les alarmes vers toutes les applications à l'écoute des alarmes.

Alarmes ignorant les fuseaux horaires

Ce genre d'alarmes est distribué en se basant sur l'heure locale de l'appareil. Si l'utilisateur du dispositif modifie son fuseau horaire, l'alarme sera distribuée en se basant sur le nouveau fuseau horaire. Par exemple, si un utilisateur est à Paris et définit une alarme qui devrait être envoyée à 12 heures CET (Central European Time) et que l'utilisateur se rende à San Francisco, l'alarme sera déclanchée à 12 PM PDT (Pacific Daylight Time).
 
// Ceci est la date de planification de l'alarme
var myDate  = new Date("May 15, 2012 16:20:00");

// Les données arbitraires passées à l'alarme
var data    = {
  foo: "bar"
}

// La chaîne "ignoreTimezone" est se qui permet d'ignorer le fuseau horaire
var request = navigator.mozAlarms.add(myDate, "ignoreTimezone", data);

request.onsuccess = function () {
  console.log("L'alarme a été déclanchée");
};

request.onerror = function () { 
  console.log("Une erreur s'est produite : " + this.error.name);
};

Alarmes respectant les fuseaux horaires

Ce genre d'alarmes est envoyé selon l'heure dans le fuseau horaire défini lors de la programmation. Si pour quelque raison, l'utilisateur du dispositif modifie son fuseau horaire, l'alarme sera déclenchée en se basant sur le fuseau horaire d'origine. Par exemple, si un utilisateur est à Paris et programme une alarme pour 12 heures CET (Central European Time) et que l'utilisateur se rende à San Francisco, l'alarme se déclenchera à 3 AM PDT (Pacific Daylight Time).
// Ceci est la date de planification de l'alarme
var myDate  = new Date("May 15, 2012 16:20:00");

// Les données arbitraires passées à l'alarme
var data    = {
  foo: "bar"
}

// La chaîne "honorTimezone" est se qui permet de garder le fuseau horaire
var request = navigator.mozAlarms.add(myDate, "honorTimezone", data);

request.onsuccess = function () {
  console.log("L'alarme a été déclanchée");
};

request.onerror = function () { 
  console.log("Une erreur s'est produite : " + this.error.name);
};

Gérer les alarmes

Une fois que l'alarme est prévue, il est encore possible de la gérer.
 

La méthode  MozAlarmsManager.getAll va retourner la liste complète des alarmes programmées par l'application. Cette liste est un Array d'objets mozAlarm.

mozAlarm

Those objects are anonymous JavaScript objects with the following properties:

id
A number representing the id of the alarm
date
A Date object representing the scheduled time for the alarm
respectTimezone
A string indicating if the alarm must respect or ignore the timezone information of the date object. Its value can be ignoreTimezone or honorTimezone
data
A JavaScript object contaning any data that were stored with the alarm

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("Une erreur s'est produite : " + this.error.name);
};

La méthode MozAlarmsManager.remove est utilisée pour dé-programmer une alarme existante.

var alarmId;

// Programme une alarme est stocke son id
var request = navigator.mozAlarms.add(new Date("May 15, 2012 16:20:00"), "honorTimezone");

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

// ...

// Plus tard, on retire l'alarme si elle existe
if (alarmId) {
  navigator.mozAlarms.remove(alarmId);
}

Manipuler les alarmes

N'importe quelle application peut réagir lorsqu'une alarme est envoyée par le système
Afin d'être en mesure de gérer des alarmes, une application doit s'inscrire comme étant elle-même un gestionnaire d'alarme. C'est possible en deux étapes grâce au System Messaging API :
 

Tout d'abord, les applications doivent inclure alarm au messages property of its application manifest avec l'URL du document qui enregistre la fonction de rappel à utiliser lorsqu'une alarme est envoyée.

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

Pour finir, l'application doit lier une fonction de rappel avec le message d'alarme. Cela se fait à l'aide de la méthode navigator.mozSetMessageHandler . Cette fonction de rappel va recevoir un objet mozAlarm contenant les données associées à l'alarme.

navigator.mozSetMessageHandler("alarm", function (mozAlarm) { 
  alert("alarme déclanchée : " + JSON.stringify(mozAlarm.data)); 
});
Si une application souhaite savoir s'il existe une alarme en attente au niveau du système, il est possible d'utiliser la méthode  navigator.mozHasPendingMessage avec la valeur alarm.
navigator.mozHasPendingMessage("alarm"); 

Spécifications

Spécification Statut Commentaire
Web Alarms API Working Draft Initial specification.

Compatibilité des navigateurs

Fonctionnalité Chrome Firefox (Gecko) Internet Explorer Opera Safari
Support de base
? 16 (16) moz Pas de support Pas de support Pas de support
Fonctionnalité Android Chrome pour Android Firefox Mobile (Gecko) IE Mobile Opera Mobile Safari Mobile
Support de base
? Pas de support 10.0 (10) moz Pas de support Pas de support Pas de support

Voir aussi

Étiquettes et contributeurs liés au document

 Contributeurs à cette page : goofy_bz, wordsbybird
 Dernière mise à jour par : goofy_bz,