Simple Push

El Simple Push API, también conocido como Push Notification API, provee a las aplicaciones la habilidad de ser despertadas para recibir notificaciones. Usted puede utilizar Simple Push como un mecanismo de sincronización, o incluso para traer datos desde servidores de terceros.

Un "push" (empujón) no es más que un evento enviado a un servidor remoto. Así es como funciona: una aplicación usa el Simple Push API para solicitar una URL especial y única llamada endpoint (punto final). Esta solicitud viaja hacia un servidor existente mantenido por Mozilla especialmente para este proposito (este se denomina "push server"). Cuando la aplicación recibe el endpoint de vuelta desde el push server, la aplicación envía el endpoint a su propio servidor (su servidor de aplicación). El servidor de aplicación guarda este endpoint, luego cuando quiere despertar la aplicación, llama al endpoint con un número de versión, y el push server contacta a la aplicación con una notificación del número de versión. La aplicación puede hacer cualquier cosa al momento de recibir la notificación, incluso ignorarla.

El Simple Push API extiende Window.navigator con una propiedad de empuje que es un objeto PushManager, e incluye algunos eventos nuevos que usted puede recibir para monitorear el estado del empuje.

Ejemplo mostrando los conceptos básicos

Existen varias formas de usar la Simple Push API. Este ejemplos cubren los conceptos básicos de como usarla. El ejemplo consta de los siguientes pasos generales. Consulte las siguientes secciones para obtener información completa sobre cada paso.

1. Añadir configuración push al manifiesto de la aplicación
2. LLamar a PushManager.register para solicitar un endpoint
3. Enviar un endpoint a su servidor
4. Agregar a su aplicación controladores de mensajes para notificaciones push
5. Enviar una notificación desde su servidor utilizando el endpoint

1. Añadir configuración push al manifiesto de la aplicación

Usted necesita cambiar dos cosas en el manifiesto de la aplicación para poder utilizar Simple Push:

1. Campo messages - Añadir push y push-register a messages.
   Esto le hace saber a la página de aplicación que recibirá cada uno de estos eventos (push y push-register). En este ejemplo, ambos van a la misma página: "/index.html", pero también pueden usar otras páginas. Observe a continuación para mayor información sobre cada uno de estos eventos.
2. Campo permissions - Añadir que su aplicación quiere recibir notificaciones push.
   Es una buena idea proveer una descripción clara en este campo para que el usuario final entienda por qué usted necesita permisos de empuje ("push").

"messages": [
   { "push": "/index.html"},
   { "push-register": "/index.html"}
],
"permissions": {
  "push": {
    "description": "Required for being updated with new goals in soccer matches"
  }
}

2. LLamar a PushManager.register() para solicitar un endpoint

La aplicación necesita solicitar un endpoint llamando PushManager.register. Usted debe decidir cuando este debe ser llamado. Usted podría llamarlo cuando el usuario ha iniciado sesión en el servicio, o cuando el usuario decide comenzar a ver un partido de fútbol, o en cualquier otro momento. El código a continuación es una forma de hacerlo.

if (navigator.push) {
  // Solicitar el endpoint. Esto usa PushManager.register().
  var req = navigator.push.register();
  
  req.onsuccess = function(e) {
    var endpoint = req.result;
      console.log("New endpoint: " + endpoint );
      // En este punto, usted deberá usar algunos llamados para enviar el 
      // endpoint a su servidor. Por ejemplo:
      /* 
      var post = XMLHTTPRequest();
      post.open("POST", "https://your.server.here/registerEndpoint");
      post.setRequestHeader("Content-Type", "application/x-www-form-urlencoded");
      post.send("endpoint=" + encodeURIComponents( endpoint ) );
      */
      // Obviamente usted querrá añadir controladores .onload y .onerror,
      // añadir información de id del usuario, y cualquier otra cosa que podría
      // necesitar para asocial el endpoint con el usuario.
    }

   req.onerror = function(e) {
     console.error("Error getting a new endpoint: " + JSON.stringify(e));
   }
} else {
  // push no se encuentra disponible en el DOM, así que haga algo diferente.
}

3. Enviar un endpoint a su servidor

Una vez la aplicación ha recibido un endpoint, necesita enviarla a su servidor de aplicación. Hay más de una forma de hacer esto. Por ejemplo usted puede enviarla por email, o enviarla a través de POST, PUT, o incluso GET. Nosotros recomendamos que almacene el endpoint con algunos datos de usuario desde la aplicación, tales como una cookie, un username, o lo que sea que usted utilice para identificar su par enpoint-user.

Pero si usted está enviando a su servidor, nosotros recomendamos que siga estas buenas prácticas:

• Enviarla a tráves de XMLHttpRequest.
• Siempre usar HTTPS. De otro modo, si alguien intercepta su endpoint, este puede comenzar a enviar notificaciones a su aplicación.
• Usar algo para emparejar al usuario (o la instalación de la aplicación) con el endpoint, como una cookie por ejemplo.
• Mantener el endpoint a salvo! Cualquier sistema con acceso a su endpoint puede hacer que su aplicación drene la batería del usuario o amarre innecesariamente su servidor, entre otras molestias. Usted siempre puede hacer que el cliente obtenga un nuevo endpoint y descartar el antiguo, pero siempre asegurese de que su servidor reconozca el cambio.

4. Agregar a su aplicación controladores de mensajes para notificaciones push

Una vez haya configurado su endpoint siguiendo los pasos anteriores, usted está listo para hacer que su aplicación comience a escuchar mensajes push y push-register utilizando los controladores de mensajes.

Añadir un controlador de mensajes push

El controlador de mensajes push puede encontrarse en su archivo index.html o en su script main.js, o incluso en un archivo específico push-message.html que contiene solamente el controlador de mensajes. Esto puede ser útil si un mensaje push es enviado y su aplicación se encuentra cerrada, porque cargará solamente una pequeña porción del código HTML/JavaScript, y usted puede decidir si la aplicación necesita estar completamente abierta o puede hacer algo en segundo plano. Donde sea que usted decida ubicar el controlador de mensajes push, asegurese de que el manifiesto apunte a la ubicación correcta (ver el primer paso anterior), de otro modo su aplicación podría no obtener actualizaciones. Aquí hay un ejemplo de un controlador de mensajes push:

if (window.navigator.mozSetMessageHandler) {
  window.navigator.mozSetMessageHandler('push', function(e) {
    console.log('My endpoint is ' + e.pushEndpoint);
    console.log('My new version is ' +  e.version);
    // Recuerde que usted puede controlar aquí si tiene más de
    // un pushEndpoint
    if (e.pushEndpoint === emailEndpoint) {
      emailHandler(e.version);
    } else if (e.pushEndpoint === imEndpoint) {
      imHandler(e.version);
    }
  });
} else {
  // Controlador No message
}

Añadir un controlador de mensajes push-register

Un mensaje push-register será enviado a todas las aplicaciones cuando el dispositivo cambie su identificador interno (llamado el UAID o User Agent Identifier). Esto puede deberse a que el servidor push ha cambiado, o se ha caido y necesita recuperarse, o cualquier otra circunstancia. Si cualquiera de estas cosas llegara a ocurrir, ustedes DEBE registrar de nuevo todos sus endpoints, porque sus previos endpoints ya no serán válidos. Por lo tanto su aplicación necesita implementar un controlador de mensajes push-register. Observe el siguiente código de ejemplo.

if (window.navigator.mozSetMessageHandler) {
  window.navigator.mozSetMessageHandler('push-register', function(e) {
    console.log('push-register received, I need to register my endpoint(s) again!');

    var req = navigator.push.register();
    req.onsuccess = function(e) {
      var endpoint = req.result;
      console.log("New endpoint: " + endpoint );
      localStorage.endpoint = endpoint;
    }

    req.onerror = function(e) {
      console.error("Error getting a new endpoint: " + JSON.stringify(e));
    }
  });
} else {
  // Controlador No message
}

5. Enviar una notificación desde su servidor utilizando el endpoint

Una vez usted tiene el endpoint en su servidor, usted puede enviar una notificación simplemente enviando una petición HTTP PUT al endpoint con el cuerpo version=<version>. Por ejemplo, imagine un endpoint con la siguiente URL:

https://updates.push.services.mozilla.com/update/abcdef01234567890abcdefabcdef01234567890abcdef

y con la version 5:

version=5

Así es como la notificación se verá utilizando curl:

curl -X PUT -d "version=5" https://updates.push.services.mozilla.com/update/abcdef01234567890abcdefabcdef01234567890abcdef

Si el servidor push esta corriendo correctamente, usted recibirá una respuesta con un 200 Status (OK) y un {} como cuerpo. También podría recibir un 200 Status indicando que el mensaje fue aceptado, pero que pudo haber sido controlado por un sistema alternativo. Si no, una respuesta error HTTP valida con un JSON explicando el error será retornada.

Recuerde que el valor de version debe ser números enteros, e incrementales. Las aplicaciones no recibirán nuevas notificaciones si la versión en menor a aquella almacenada en el servidor y/o dispositivo. Las versiones pueden ser útiles para que la aplicación indique si existen eventos "perdidos" que realmente debería verificar. Usted también podriá simplemente usar el UTC (el número de segundos desde la media noche del 1 de enero de 1970, GMT) actual si el valor de la versión no es muy importante para usted.

Anular el registro de un endpoint

Una vez haya terminado de utilizar el endpoint y no desee recibir más notificaciones, le rogamos anular el registro del antiguo endpoint mediante PushManager.unregister. Esto limpiará la cantidad de datos que el dispositivo envía al servidor push, y además disminuirá el consumo de batería al no enviar notificaciones de las aplicaciones que no las usen.

Especificaciones

Conpatibilidad con navegadores

Ver también

• PushManager
• Window.navigator.push
• pushJSLibrary, a push shim for browsers that do not implement the API
• SimplePush original design and discussion page