image


indigitall Browser SDK


Índice

  1. Introducción
  2. Requisitos
  3. Integración del SDK
    1. Integración del SDK en web no segura
  4. Configuración Chrome
    1. Consola de Google Firebase
    2. Service Worker
  5. Configuración Safari
  6. Configuración Firefox y Edge
  7. Funcionalidades Avanzadas
    1. Recoger DeviceID
    2. Comprobar estado
    3. Activar / Desactivar dispositivo
    4. Obtener todos los canales de interés
    5. Obtener los canales de interés suscritos
    6. Suscribirse / Desuscribirse de un canal
    7. Consultas sobre el navegador
    8. Comprobar si el navegador es compatible
    9. Comprobar si las notificaciones están activas o no
    10. LocalStorage compartido
  8. FAQs
    1. ¿Tengo que tener todo mi website en HTTPS?
    2. ¿Qué pasa si un usuario borra los datos del navegador?
    3. ¿Puedo desarrollar la integración en local, sin tener que configurar HTTPS?
    4. ¿Qué certificado SSL debo comprar para la pasarela?
    5. ¿Qué cuenta de FireBase tengo que comprar para las notificaciones?
    6. ¿Si quiero dar soporte a Safari, necesito una nueva cuenta de Apple Developer?
    7. ¿Para el certificado de Apple, qué Website Push ID debo elegir?
    8. ¿Qué parámetros puedo asociar a una notificación?

1. Introducción

En este documento se recoge toda la información necesaria para llevar a cabo la integración de la plataforma indigitall en los navegadores webs compatibles con la recepción de notificaciones, actualmente Google Chrome (a partir de la versión 42), Safari (a partir de OS X 10.9) y Firefox (desde la versión 44).

Puesto que la implementación para cada uno de los navegadores es relativamente diferente, este manual estará dividido en 3 partes: implementación común, configuración específica para Chrome, y configuración para Safari en OS X.

Este documento está dirigido a desarrolladores Web, por lo que se utilizará un lenguaje técnico cuando sea necesario, así como ejemplos de código fuente y capturas para facilitar el seguimiento del manual.

2. Requisitos

Para el correcto funcionamiento de las notificaciones en los navegadores, además de la configuración correcta de cada apartado, en el caso de Chrome y Firefox es requisito imprescindible que la web se encuentre en una ruta https (debe utilizarse un certificado SSL válido, obtenido a través de un proveedor autorizado, y utilizando cifrado TLS al menos en su versión 1.0). Además, para que una notificación sea recibida, es necesario que el navegador se encuentre en ejecución (bien en primer plano, o en segundo plano). En cambio, en Safari las notificaciones se recibirán aún con el navegador completamente cerrado.

También es importante tener en cuenta que, con la implementación actual de notificaciones remotas que ofrece Safari, los detalles de configuración no pueden ser modificados una vez configurados por primera vez (cuando el usuario acepta recibir las notificaciones, dicha configuración se descarga automáticamente y no se puede actualizar salvo que el usuario desactive y posteriormente vuelva a activar las notificaciones, momento en que se descargará de nuevo la configuración). Esta configuración incluye el icono, y la plantilla de la URL a abrir tras hacer click en una notificación (se explica con más precisión en el apartado de Safari).

3. Integración del SDK

Opción 1: Datos de configuración en la carpeta indigitall.

Debemos adaptar la configuración del SDK que se encuentra en la carpeta de indigitall, en el archivo indigitall.json con nuestros datos de configuración. El archivo service-worker.min.js debemos moverlo a la raiz del sitio web, de forma que sea accesible desde /service-worker.min.js.

Para poder utilizar las opciones que ofrece la librería, en primer lugar debemos importar desde nuestro HTML el javascript principal que dará acceso a toda la funcionalidad.

Debemos incorporar el script al final del documento (o bien utilizando el atributo async disponible en la especificación HTML5). En este caso, para asegurarnos de que la llamada de inicialización se realiza en el momento adecuado, cuando el SDK se encuentre completamente cargado, debemos escuchar el evento ‘indigitallReady’. A continuación se muestra un ejemplo de implementación:

index.html

<!DOCTYPE html>
<html>
<head>
  <title>Ejemplo indigitall</title>
</head>
<body>
  <script>
      document.addEventListener('indigitallReady', function() {
        navigator.indigitall.loadIndigitall(function(){
            console.log('Successs!!');
          }, function(error){
            console.log('Error!! ' + error);
        });
      });
  </script>
  <script type="text/javascript"src="/indigitall/indigitall.min.js?v=x.x.x"></script>
</body>
</html>

/indigitall/indigitall.json

{
  "APP_TOKEN": "APP_TOKEN",
  "WEB_SITE_PUSH_ID": "web.com.domain",
  "ICON": "/indigitall/logo.png",
  "TITLE": "indigitall",
  "DEBUG_MODE": true,
  "VAPID_PUBLIC_KEY": "BPNci1jg-deZqNqeFdeYWodJ78bF7fsYvbbsDlgO..."
}

Los cambios anteriores son todos los necesarios para conseguir integrar completamente la plataforma de indigitall en el sitio web; restando únicamente la configuración particular necesaria para cada plataforma. En el archivo de configuración indigitall.json, es necesario indicar los siguientes parámetros:

{
  "APP_TOKEN": "Identificador de la aplicación en la plataforma de indigitall",

  "WEB_SITE_PUSH_ID": "Identificador del sitio web configurado en el Developer Center de Apple. Se explica con más detalle en la sección correspondiente a Safari",

  "ICON": "Icono que se mostrará por defecto en chrome en caso de no enviar ningún otro asociado a la notificación (en safari se muestra el icono predefinido al configurar la aplicación)",

  "TITLE": "Título por defecto para las notificaciones en caso de que no se indique ningún otro al realizar el envío de la notificación",

  "DEBUG_MODE": "Valor booleano (true/false) indicando si se debe imprimir por la consola web información de debug. Debe estar a true en el entorno de desarrollo y a false en el de producción",

  "VAPID_PUBLIC_KEY": "String de clave pública VAPID del servidor de push. La proporciona el equipo de indigitall al crear la aplicación"
}

Opción 2: Datos de configuración en otra carpeta.

Si se guarda el archivo indigitall.json en otra carpeta que no sea la carpeta indigitall es necesario indicarselo al SDK en el momento de la inicialización de la librería:

index.html

<!DOCTYPE html>
<html>
<head>
  <title>Ejemplo indigitall</title>
</head>
<body>
  <script>
      document.addEventListener('indigitallReady', function() {
        navigator.indigitall.loadIndigitall('/CARPETA_CONFIGURACION/',function(){
            console.log('Successs!!');
          }, function(error){
            console.log('Error!! ' + error);
        });
      });
  </script>
  <script type="text/javascript"src="/indigitall/indigitall.min.js?v=x.x.x"></script>
</body>
</html>

3.1. Integración del SDK en web no segura

Para implementar indigitall en una web no segura, hay que preparar una pasarela en HTTPS. Tendremos 3 puntos, la web no segura en un dominio, y en otro dominio seguro HTTPS, tendremos la carpeta de indigitall y una pasarela donde pediremos al usuario los permisos para las notificaciones.

La pasarela se implementa siguiendo la integración normal del SDK. Aqui vamos a cubrir la configuración del SDK en la web no segura.

Es importante pasar el Objeto de configuración, con el parametro INDIGITALL_FOLDER, y no confundirnos y pasar un string, porque sino el SDK no se iniciará como esclavo, sino como si fuera una página independiente.

index.html

<!DOCTYPE html>
<html>
<head>
  <title>Ejemplo indigitall</title>
</head>
<body>
  <script>
      document.addEventListener('indigitallReady', function() {
        var options = {
          INDIGITALL_FOLDER: 'https://domain/indigitall/'
        };
        navigator.indigitall.loadIndigitall(options, onLoadSuccess, onLoadError);
      });

      function onLoadSuccess(newUser){
        if(newUser){
          console.log('El usuario no tiene notificaciones, le mostramos un popup o redirigimos a la web de registro');
        }else{
          console.log('El usuario ya tiene las notificaciones activas, no le mostramos nada');
        }
      }

      function onLoadError(error){
        console.error('Error!! ' + error);
      }
  </script>
  <script type="text/javascript"src="/indigitall/indigitall.min.js?v=x.x.x"></script>
</body>
</html>

La función Success recibe como parámetro un booleano que indica si el usuario es nuevo y no tiene las notificaciones activadas o no.

Esta funcionalidad puede usarse directamente antes de inicializar el SDK en la siguiente función Comprobar si las notificaciones están activas o no así como tambien es posible comprobar si el navegador soporta notificaciones (aunque la inicialización de la libreria fallará igualmente en tal caso) Comprobar si el navegador es compatible.

4. Configuración de Chrome

4.1. Consola de Firebase

En este tutorial se detalla cómo obtener el FCM ServerKey, necesario para la recepción de notificaciones en Chrome.

4.2. Service worker

Hay que mover el fichero service­worker.js. Este fichero es importante que se encuentre en la raíz de la web, ya que en caso contrario el scope de dicho service worker no sería el adecuado para procesar la información relativa a las notificaciones push y no sería posible llevar a cabo el intercambio de información entre en el worker y la página; por lo que algunas de las funcionalidades propias de la plataforma indigitall (relativas al uso de filtros y estadísticas) podrían verse afectadas.

5. Configuración de Safari

Para completar la configuración en Safari, debemos generar un Website Push ID y un Website Push ID Certificate (.p12 y su contraseña).

Tutorial

Además el desarrollador tendrá que comunicar al equipo de indigitall los dominios permitidos desde donde se inscribirán los usuarios al servicio, y el icono a mostrar en las notificaciones (imagen cuadrada, de 256x256px).

6. Configuración Firefox y Edge

Si ya se ha configurado correctamente la librería para que funcione con Chrome, no es necesaria ninguna acción adicional para configurar Firefox y Edge, ya que la recepción funciona también al incluir el service worker.

7. Funcionalidades Avanzadas

Además de la configuración para la recepción de notificaciones, la plataforma de indigitall ofrece diferentes opciones para enriquecer la experiencia de usuario. De este modo, al igual que para otras plataformas, se permite la suscripción a categorías, o la anulación de la suscripción a las notificaciones. Para esto, la librería ofrece las llamadas que se indican a continuación.

Todas las funcionalidades de la librería están accesibles a través del objeto navigator.indigitall; a través del cual podemos acceder, además de a las funciones que comentaremos posteriormente, a las siguientes propiedades (todas ellas deben utilizarse solo en modo lectura, su modificación no tendrá ningún efecto en el funcionamiento de la librería):

APP_TOKEN: Identificador de la aplicación en indigitall.

DEF_IMG: Imagen por defecto utilizada en las notificaciones.

DEF_TITLE: Título por defecto para las notificaciones.

DEVICE_ID: Identificador del dispositivo en la plataforma indigitall

PUSH_TOKEN: En chrome, el push token obtenido en la suscripción al GCM

PW_ID: Identificador de la aplicación en el servidor de push.

WEB_SITE_PUSH_ID: Id del sitio web en apple.

isChrome: Propiedad booleana para comprobar si un navegador es Chrome.

isSafari: Propiedad booleana para comprobar si un navegador es Safari.

isFirefox: Propiedad booleana para comprobar si un navegador es Firefox.

En cuanto a las funcionalidades, la librería ofrece las siguientes las llamadas detalladas a continuación:

7.1 Recoger DeviceID

Cuando hablamos de DeviceID, nos referimos al identificador único que la librería de indigitall genera para identificar los navegadores y poder enviarles mensajes push. Este ejemplo indica cómo recoger este dato para poder trabajar con él.

document.addEventListener('indigitallReady', function() {
  navigator.indigitall.loadIndigitall(function(){
      var device_id = navigator.indigitall.getDeviceId();
    }
  );
});

Nota: el DeviceID se genera por primera vez cuando la SDK de indigitall ha terminado de cargar (callback success del método loadIndigitall). Después quedará guardado en el LocalStorage con la clave indDeviceId

7.2 Comprobar estado

La librería de indigitall permite activar y desactivar un dispositivo, de modo que se pueda ofrecer al usuario la posibilidad de desactivar las notificaciones. Para comprobar el estado actual, existe la llamada: navigator.indigitall.getStatus(successCallback, errorCallback);

Esta llamada recibe como parámetros los callbacks para caso de éxito o caso de encontrar algún error. En caso de éxito, la función callback recibirá un objeto con un campo status de tipo String con el valor ‘enabled’ o ‘disabled’. En caso de error, el parámetro será un String indicando el tipo de error.

Si se implementa una ventana propia para preguntar al usuario si quiere recibir o no notificaciones, hay que mostrarla si el parámetro del callback de éxito tiene p.status == “enabled”. De esta forma, evitaremos preguntar varias veces al usuario.

7.3 Activar / Desactivar dispositivo

Las llamadas que permitirán activar o desactivar el dispositivo tienen una estructura exactamente igual; y ambas pueden ser llamadas sea cual sea el estado del dispositivo. En caso de realizar una llamada para activar un dispositivo ya activado (o desactivar un dispositivo ya inactivo); la llamada devolverá error indicándolo en el mensaje del callback. Las llamadas disponibles son:

navigator.indigitall.enable(successCallback, errorCallback); navigator.indigitall.disable(successCallback, errorCallback);

En ambos casos, en caso de éxito, el callback successCallback recibirá un parámetro con el mensaje ‘Actualización correcta’. En caso de que suceda cualquier problema, se enviará a errorCallback un String con el correspondiente mensaje de error.

7.4 Obtener todos los canales de interés

Al igual que en el resto de plataformas, en la web existe la posibilidad de suscribir a los usuarios a canales de interés creados en el panel de indigitall. Para el manejo de dichos canales de suscripción, se ofrecen los métodos que se indican a continuación. En primer lugar, el siguiente método obtendrá todos los canales de interés disponibles para la aplicación actual:

navigator.indigitall.getAllCategories(successCallback, errorCallback);

Del mismo modo que en las llamadas anteriores, los parámetros serán sendos callbacks, para caso de éxito o caso de error. En caso de éxito, la función successCallback recibirá como parámetro un Array con todas las categorías disponibles; siendo cada categoría un objeto de la forma:

{
    "id": "identificador",
    "name": "name",
    "parent": "id_parent"
}

En el campo parent, el valor será el valor id de la categoría padre o, en caso de tratarse de una categoría raíz, la cadena ‘#’.En caso de error, la función errorCallback recibirá un String con la descripción del error.

7.5 Obtener los canales de interés suscritos

Además de la llamada anterior, para obtener las etiquetas a las que se encuentra ya suscrito nuestro dispositivo, disponemos de la siguiente llamada:

navigator.indigitall.getSubscriptions(successCallback, errorCallback);

La utilización de esta llamada es exactamente igual a la anterior, y la estructura de la respuesta, tanto del successCallback como del errorCallback es idéntica a la anterior.

7.6 Suscribirse / Desuscribirse de un canal

Los métodos que nos permitirán suscribir o desuscribir a los usuarios de los grupos de interés disponibles, son los siguientes:

navigator.indigitall.subscribe(channels, successCallback, errorCallback); navigator.indigitall.unsubscribe(channels, successCallback, errorCallback);

En este caso, además de los habituales callbacks; es necesario indicar los canales a los que queremos realizar o eliminar las suscripciones. La forma de indicarlos será mediante un array de identificadores de etiquetas, por ejemplo:

Varios:
[“identificador1”, “identificador2”];
Uno solo:
[“identificador1”];

Tanto a, como b, serían variables válidas para la llamada subscribe/unsubscribe. Es importante que, aunque la suscripción o desuscripción sea a una sola categoría, está se debe enviar dentro de un array; ya que en caso contrario se producirá error y siempre se llamará a errorCallback.

7.7 Consultas sobre el navegador

Las variables navigator.indigitall.isChrome, navigator.indigitall.isFirefox y navigator.indigitall.isSafari servirán para distinguir el navegador del cliente. También se puede usar la función navigator.indigitall.isAppleMobile() que devuelve true en caso de que el cliente sea un iPhone o un iPad. Estas variables y funciones son muy útiles para personalizar la experiencia del cliente. El servicio de notificaciones no está disponible para iPhones/iPads. Estas funciones presentan una solución para mostrar los mensajes de suscripción únicamente a los clientes soportados.

7.8 Comprobar si el navegador es compatible

Está disponible la función navigator.indigitall.browserSupported() que devuelve un booleano indicando si el navegador soporta las notificaciones o no.

7.9 Comprobar si las notificaciones están activas o no

La función navigator.indigitall.notificationsActive() devuelve un booleano si las notificaciones están activas para el usuario. Si no están activas puede deberse a varios motivos, como que el usuario no tenga DeviceID porque haya borrado las cookies, o que no tenga los permisos de notificaciones.

7.10 LocalStorage compartido

La función navigator.indigitall.write(key, value, callback) te permite escribir un registro en el local storage de la pasarela, accesible desde cualquier web no segura que inicialice el SDK de indigitall y que apunte a la misma pasarela.

La función navigator.indigitall.write(key, callback) te permite leer un registro en el local storage de la pasarela desde cualquier web no segura que inicialice el SDK de indigitall y que apunte a la misma pasarela.

8. FAQs

¿Tengo que tener todo mi website en HTTPS?

Por requisitos de seguridad, tanto Chrome como Firefox exigen que la petición de permisos se realice en un dominio que corra bajo HTTPS. No es necesario que todo el website esté en HTTPS, únicamente la página que realice la llamada a loadIndigitall, que es la encargada de lanzar el prompt de petición de permisos e instalar el servicio que escucha las notificaciones en background.

¿Qué pasa si un usuario borra los datos del navegador?

Cuando un usuario borra los datos en Chrome o Firefox, se desinstala el Service Worker, que es el encargado de escuchar en background la recepción de notificaciones. Para que se vuelva a instalar en su navegador es necesario que cargue la página donde se ejecuta la llamada a loadIndigitall. Esta instalación es totalmente transparente para el cliente, es decir, no se vuelve a lanzar el prompt del navegador para pedir los permisos. Por este motivo, recomendamos que la llamada a loadIndigitall se haga, si es posible, en una página “de paso” (como podría ser el home de nuestro website).

¿Puedo desarrollar la integración en local, sin tener que configurar HTTPS?

Sí, es posible. Aunque no corra en HTTPS, Chrome y Firefox hacen una “excepción de seguridad” con localhost, para facilitar tareas de desarrollo. En el caso de Safari, Apple comprueba que el dominio desde el que pides los permisos estén en la lista de dominios permitidos. Escríbenos a soporte@indigitall.net para que añadamos 127.0.0.1, y despliega en el puerto 80 de localhost. Nota: para hacer las pruebas en Safari debes acceder al dominio 127.0.0.1, no a localhost.

¿Qué certificado SSL debo comprar para la pasarela?

Cualquier certificado válido para web. Si no tienes ya un proveedor te recomendamos Let's Encrypt.

Let’s Encrypt es una autoridad de certificación (CA) gratuita, automatizada y abierta, que se ejecuta en beneficio del público por el Grupo de Investigación de Seguridad de Internet (ISRG). Esto hace que sea posible la obtención de certificados de confianza de explorador para tus dominios sin coste que se renuevan automáticamente cada 90 días. Con Let’s Encrypt no hay configuraciones complicadas, no hay mensajes de correo electrónico de validación y se pueden tener múltiples certificados instalados en tus cuentas de alojamiento, para cada dominio y subdominio que elijas. Los certificados son de dominio-validado y no requieren una dirección IP dedicada. Es apto para los principales navegadores.

En internet encontrarás multitud de guías y tutoriales para instalar un certificado con Let's Encrypt, aqui tienes uno Guía Let's Encrypt.

¿Qué cuenta de FireBase tengo que comprar para las notificaciones?

Cualquier cuenta es válida, si ya posees una de pago, puedes usarla, sino puedes usar la gratuita Precios de FireBase.

¿Si quiero dar soporte a Safari, necesito una nueva cuenta de Apple Developer?

Una sola cuenta de Apple Developer te sirve tanto para App IOS como para la parte web para Safari. En este sentido es necesario que sea una cuenta de pago para poder generar los certificados, sino no aparecerá la pestaña de 'Certificados' en la consola de Apple.

¿Para el certificado de Apple, qué Website Push ID debo elegir?

Se recomienda que sea el dominio del sitio al reves, pero puede ser cualquiera que esté libre.

¿Qué parámetros puedo asociar a una notificación?

  • Título
  • Cuerpo
  • Imagen
  • URL

Y es posible pasar parámetros adicionales en la URL usando QueryString.