3. Requisitos generales
3.1. Requisitos técnicos
3.1.1. Gestión del código fuente, distribución y publicación
- R02.01.01 Las PWA publicadas por el Ayuntamiento son propiedad de éste y, por tanto, habrá que proporcionar el código fuente y todo el material necesario una vez publicado el proyecto. El código fuente deberá quedar correctamente publicado en la rama del GitLab que proporcionará la OSAM.
- R02.01.02 Por defecto, cualquier recurso que necesiten las PWA (archivos de configuración, archivos, imágenes, servidor de aplicaciones / web, ...), deberá estar instalado en los servidores del IMI o Ayuntamiento. En caso de que no se considere posible, habrá que justificarlo a la OSAM de forma previa y será necesaria su aprobación.
- R02.01.03 Las nuevas PWA que se creen deberán poder ser publicadas bajo una licencia OpenSource por parte del Ayuntamiento. En caso de no ser posible o tener inconvenientes, hay que hablarlo con la OSAM para acordar una solución. Antes de comenzar el proyecto, es necesario que el equipo de desarrollo se ponga en contacto con el de la OSAM para acordar el tipo de licencia.
- R02.01.04 Desarrollo: Durante el proceso de desarrollo, el proveedor deberá utilizar exclusivamente sus credenciales, claves y recursos propios diferentes a los de producción, para todas aquellas herramientas externas, tales como la Key de Analytics, Firebase y Google Maps.
- R02.01.05 Publicación: Mientras que para las versiones de producción se utilizarán las credenciales, claves y recursos propios de la OSAM. Estos códigos se facilitarán al proveedor para que los introduzca en el código fuente antes de publicar el proyecto. Se deberá tener en cuenta que las PWA del Ayuntamiento de Barcelona se publicarán siempre siguiendo el siguiente patrón de URL: https://webapp.barcelona.cat**_/<nombre_del_proyecto>.
- La aprobación de la URL concreta y su creación deberá hacerse mediante una petición a la OSAM o a la Dirección de Comunicación Digital del Ayuntamiento.
3.1.2. Diseño Visual
- R02.02.01. Las PWA desarrolladas para el Ayuntamiento de Barcelona deben seguir la guía de estilo definida a tal efecto por la Dirección de Comunicación Digital y que se puede consultar en el siguiente documento: Guía estilo gráfico para Progressive Web Apps.
3.1.3. Política de uso de librerías, herramientas y contenido de terceros
Se debe cumplir el requerimiento de que las nuevas PWA puedan ser publicadas bajo una licencia Open Source..
- R02.03.01 En caso de utilizar mapas hay que garantizar la normativa de uso vigente, utilizando siempre la última versión disponible del sistema.
- R02.03.02 Las PWAs no pueden tener materiales con derechos de autor o propiedad de terceros (incluyendo música, fotos, vídeo, esculturas, pinturas y otras obras de arte o imágenes publicadas en sitios web o en la televisión, películas u otros medios) sin la correspondiente cesión de los derechos de explotación de forma expresa y por escrito.
- R02.03.03 La plataforma obligatoria para trackear el uso de la PWA será Google Analytics.
- R02.03.04 Se recomienda el uso de la plataforma Google Firebase para cumplir con las recomendaciones de desarrollo de las PWAs.
3.1.4. Analítica y feedback de usuario
Google Analytics: Las analíticas y métricas se harán con Google Analytics de manera transparente gracias al módulo común Core.js. Ver sección 3.2.1 Core.js para obtener información sobre la configuración y utilizar la librería para el marcaje de analíticas.
- R02.04.01 Registro de datos: La PWA debe registrar como mínimo las pantallas visualizadas en la PWA como eventos obligatorios. También se ha de registrar el evento de cambio de idioma, identificado mediante un label con un código de dos letras, según el idioma ISO correspondiente (ex.CA, ES, EN, FR, ...).
- R02.04.02 Seguimiento de datos sin conexión: Se debe usar el service worker que ofrece el paquete Workbox de Google. De este modo, se evita que en un entorno sin conexión a internet, los accesos a Google Analytics con el seguimiento de eventos fallen y se pierdan las medidas de este periodo. Se puede encontrar más información aquí.
3.1.5. Informes de errores
- R02.05.01 Las aplicaciones deben integrar herramientas para la detección e informe de errores de ejecución una vez estén publicadas en producción. Para aplicaciones web identifican diferentes herramientas:
- Sentry es una de las herramientas más utilizadas por las grandes compañías para la generación de informes de errores de las aplicaciones publicadas. Se integra fácilmente con multitud de frameworks frontend, backend y nativos, así como herramientas de gestión de proyecto como Jira y gestores de código.
- El soporte de Google Analytics para el seguimiento de errores es mínimo, pero se puede integrar igualmente para tener esta información también a los dashboards.
- Airbrake es también una potente herramienta para el seguimiento de informes de error, con integraciones con muchos lenguajes y frameworks de desarrollo. Sin embargo, se puede integrar fácilmente con herramientas de gestión de proyecto y de control de código.
- Raygun dispone de un proyecto denominado Crash Reporting. Se puede integrar fácilmente con frameworks de frontend, y nuevamente se puede integrar con herramientas de gestión de proyecto y control de código.
- Rollbar es una suite para el seguimiento de errores. Como el resto, se puede usar fácilmente con diferentes frameworks frontend y herramientas de gestión de proyecto y control de código.
- Countly, dentro de su ecosistema de analíticas para la web, ofrece plugins de informes de errores.
3.1.6.Versionado
- R02.06.01 Es necesario que las PWA del Ayuntamiento se actualicen correctamente en segundo plano cuando se detectan cambios en el servidor (mediante el service worker).
- R02.06.02 Semantic versioning: Las PWA deben incluir control de versiones para hacer la trazabilidad de qué versión está ejecutando el usuario. El número de versión es seguir el estándar semver, que divide la versión en tres números separados por puntos: <mayor>. <Minor>. <Patch>, donde:
- major: número de versión que se incrementa cada vez que se hace una actualización no retrocompatible, o por motivos comerciales (denotar una gran actualización o remodelación).
- minor: número de revisión que incluye cambios retrocompatibles con versiones anteriores.
- patch: cambio menor para solventar bugs y que no incluye ninguna nueva funcionalidad.
- Por tanto, el número de versión se debe modificar con cada publicación de la app actualizándolo de acuerdo con los cambios que contiene y según el convenio descrito anteriormente. Verificar que la PWA se actualiza correctamente en segundo plano cuando se detectan los cambios al servidor (mediante el service worker).
- R02.06.03 Fecha de publicación: En el número de la versión resultante se le añadirá al final una marca temporal, para identificar fácilmente la fecha de publicación, en formato YYYYMMDD.
- Por ejemplo:
- Versión: 1.0.0_20190814
- Se identifica como la versión 1.0.0 publicada el 14 de agosto de 2019.
- Por ejemplo:
- R02.06.04 Visibilidad del número de versión: El número de versión actual de la PWA debe ser visible para el usuario final en la pantalla de ayuda, siguiendo las especificaciones de la guía de estilos: tamaño y color de letra discretos y no enfatizados, ya que se trata de una información útil pero no relacionada con los contenidos de la aplicación.
3.1.7. Auditoria Lighthouse
R02.07.01 Toda PWA deberá cumplir con un mínimo del 80% de rendimiento a la auditoría de Lighthouse (Chrome developer tools).
3.2. Librerias del Ayuntamiento
El Ayuntamiento de Barcelona dispone de herramientas desarrolladas internamente que facilitan la homogeneidad y la calidad de algunas funcionalidades.
A continuación se detallan aquellas que se han considerado para ser utilizadas en las nuevas PWA.
3.2.1. Core.js
Core.js se compone de una hoja de estilos CSS y una librería JavaScript que, entre otros, proporcionan las siguientes funcionalidades que se pueden utilizar de manera independiente y opcional:
Cumplimiento de la normativa de información de uso de cookies y la aceptación (parcial o total) o negación por parte del usuario
Tracking en Google Analytics de todos los clics hechos en los enlaces (anchor) de la página
Instalación
Añadir al documento index.html las dependencias de CSS y JS:
<link type="text/css" rel="stylesheet" href="https://www.barcelona.cat/assets/core/stylesheets/core.css" media="all" />
<script type="application/javascript" src="https://www.barcelona.cat/assets/core/javascripts/core.js"></script>
Funcionalidades requeridas
- R02.08.01: Notificación de uso de cookies y gestión por parte del usuario
<script type="application/javascript">
bcn.cookiescontrol();
</script>
- R02.08.02: Marcajes a Google Analytics
<script type="application/javascript">
// Core.js: track current page view and manage links of current DOM status
bcn.statistics({
keys: [gaId],
test: IS_TEST,
tracklinks: { 'links': true }
});
</script>
Cada vez que se modifique el DOM de la PWA (cambios de pantalla, aparición de nuevo contenido), se deberá invocar nuevamente la función bcn.statistics para que Core.js añada los gestores de eventos adecuados. Implícitamente, esta función enviará un marcaje de página visitada (pageviews), por lo que es importante llamarla sólo una vez en cada re-render para evitar marcajes duplicados.
El atributo de configuración test se ha de informar de la siguiente manera:
- Entornos no productivos (DEV/UAT/...): valor true
- Entorno productivo (PRO): valor false o bien no informar este atributo.
Personalización de la apariencia
La notificación de uso de cookies que genera el Core.js tiene una apariencia totalmente corporativa siguiendo los estilos fijados por las webs del Ayuntamiento. A las PWA, sin embargo, el diseño puede ser totalmente diferente, por lo que se puede querer ajustar esta notificación para que se integre visualmente con el resto de la aplicación.
Para lograr esto será necesario crear una hoja de estilos CSS donde se redefinan colores, fuentes, transformaciones de texto, etc.
A continuación aparece una hoja SCSS que modifica la notificación para tener una apariencia más cercana a Google Material.
$cc-font-family: "Roboto", "Helvetica", "Arial", sans-serif;
$cc-font-color: rgba(0, 0, 0, 0.54);
$cc-background-color: inherit;
#bcn-ccwr.v2014.desktop,
#bcn-ccwr.v2014.mobile {
&, & * {
background-color: $cc-background-color !important;
font-family: $cc-font-family !important;
color: $cc-font-color !important;
}
button, a {
text-transform: uppercase;
text-decoration: none;
font-weight: 500;
}
.bcn-cc-content {
// Propietats específiques dels paràgrafs de text
.bcn-cc-info p { }
.bcn-cc-buttons {
// Propietats específiques del botó 'Continuar'
.bcn-cc-agree {
border: 1px solid;
}
// Propietats específiques de l'enllaç on trobar més informació
a.bcn-cc-more-info {
text-transform: none;
&::after {
font-family: 'Material Icons';
content: " \e890";
}
}
}
}
}
Notificación original:
Notificación resultante de aplicar los nuevos estilos:
3.3. Requisitos Funcionales
- Splash screen:
- R03.01.01 Se recomienda que se presente un mínimo de 2 segundos al iniciar la PWA.
- R03.01.02 En el caso de que el splash screen tenga alguna animación o justo después de que haya alguna animación tipo carrusel de fotos, hay que realizar una de las siguientes acciones:
- Pasados 5 segundos la PWA vaya a la home sin que el usuario haga nada
- Que la pantalla tenga una indicación similar a "toca la pantalla para iniciar la PWA”
- R03.01.03 Hay que seguir la guía de estilos referenciada en la sección 3.1.2 Diseño Visual
- Las splash screen no funcionan en iOS entre las versiones 8 y 11.2 por un bug del sistema operativo resuelto en la versión 11.3.
- Icono:
- R03.01.04 Es requerido añadir tantas resoluciones de icono como sea necesario para apoyar las diferentes resoluciones de los dispositivos móviles Android y iOS.
- R03.01.05 Entre las resoluciones indicadas anteriormente, se debe referenciar un icono de 192x192 píxeles.
- R03.01.06 Hay que seguir la guía de estilos referenciada en la sección 3.1.2 Diseño Visual.
- R03.01.07 Caso especial es el icono adaptativo de Android que apareció con la versión 8.0. El apoyo a este tipo de icono se introdujo en el manifiesto de las PWA en septiembre de 2018 como "maskable icon".
- Se debe incluir un apartado de ayuda para los usuarios de fácil acceso a todas las PWAs. Como mínimo contendrá:
- R03.01.08 Descripción de la app, objetivos y apartados
- R03.01.09 Autoría del proyecto
- R03.01.10 Número de versión de la PWA (cogiéndolo dinámicamente del código).
- R03.01.11 Habrá que indicar si la versión de la PWA está funcionando en un entorno de Pre-producción o Producción, donde el primero es un entorno de pruebas.
- R03.01.12 Si la PWA está abierta, al clicar de nuevo en el icono hay que abrirla en el punto que se encontraba, y no arrancarla de nuevo.
- R03.01.13 Si la PWA requiere descargar un volumen de datos "onfly" superior a 20 MB, se informará previamente al usuario con un mensaje advirtiendo la situación, dando la posibilidad de no hacerlo (explicando las consecuencias) y recomendando el uso de wifi. Si es posible por el buen funcionamiento de la PWA, esta descarga de información se haría en segundo plano.
3.3.1. Consideraciones por plataforma
A pesar de tener una especificación clara, las PWA no se ejecutan en un entorno homogéneo entre plataformas nativas. Apple, por ejemplo, como sistema propietario muy cerrado, añade restricciones de memoria y almacenamiento que se debe tener presente:
- Ciclo de vida de la aplicación.
- Limitaciones de los servicios workers.
- Limitaciones de API.
- Limitaciones de espacio de almacenamientos.
Microsoft tiene un gran apoyo para PWA con Windows 10, incluso las incorpora dentro de su Microsoft Store para que los usuarios puedan encontrar fácilmente. A su documentación se muestra el apoyo actual a las funcionalidades y API para las PWA.
R03.02.01 Tener presente las actualizaciones periódicas de cada sistema operativo para ser compatibles con las últimas dos versiones del navegador predeterminado de cada plataforma, siendo este navegador Safari en iOS y Chrome en Android.
Se recomienda el uso y seguimiento del soporte nativo a las diferentes API y novedades de W3C con la web Can I use, por ejemplo: https://caniuse.com/#search=pwa
3.3.2. Privacidad y protección de datos
RGPD
Las apps del Ayuntamiento de Barcelona han de cumplir con la normativa vigente sobre protección de datos y privacidad de los usuarios. En concreto, deberán tener en cuenta a nivel europeo el Reglamento General de Protección de Datos (2016/679) y a nivel estatal la Ley Orgánica de Protección de Datos y Garantía de Derechos Digitales (LO 3/2018, de 5 de diciembre).
Dado que la afectación de estas normativas va más allá del propio funcionamiento de las apps, la responsabilidad sobre la correcta aplicación de estas es del responsable o promotor de la aplicación. No obstante, y sin menoscabo de la total aplicación de estas normativas, a continuación se enumeran algunos de los requerimientos que deberán tenerse en cuenta en relación con estas y que serán validados por la OSAM:
- R03.03.01 Cuando se guarden, utilicen o se muevan datos personales, debe solicitar y recibir el consentimiento explícito e inequívoco del usuario para poder proceder. Al inicializarse la app se mostrará una pantalla en la que se solicitará su consentimiento al usuario mediante una serie de mensajes que solicitan permisos al usuario y que éste debe aceptar. Si no se aceptan estas condiciones de servicio, la app mostrará un mensaje informando al usuario y la funcionalidad quedará escondida, por lo que se debe validar que estos permisos están informados.
- R03.03.02 Para todas las apps que tengan condiciones de aceptación de servicio, se debe prever que estas condiciones pueden cambiar. Por lo tanto, debe haber un mecanismo que permita forzar a aceptar estas condiciones cuando cambien, volviendo a mostrar la pantalla en la que se solicita el consentimiento al usuario mostrando las nuevas condiciones.
- R03.03.03 Una vez el usuario ha aceptado las condiciones de servicio, la pantalla en la que se solicita su consentimiento no volverá a aparecer, a menos que las condiciones de aceptación cambien.
- R03.03.04 La información personal de los usuarios se encripta con algoritmos robustos para minimizar la afectación de brechas en la seguridad. Por el mismo motivo, las comunicaciones con servidores deberán realizarse bajo el protocolo HTTPS.
Gestión de permisos
- R03.04.01 Hay que tener en cuenta que las aplicaciones, y sus actualizaciones, deben implementar la gestión de permisos "on demand", es decir, se pida a medida que lo necesite la app, no al inicio o en un momento que por el contexto el usuario no pueda entender para qué necesita conceder estos permisos.
- R03.04.02 Siempre que esté disponible en el navegador, se hará uso de la API Permissions para consultar los permisos concedidos por el usuario a la aplicación para acceder a funcionalidades nativas.
- Para solicitar permisos se utilizarán los métodos específicos de cada API:
- Geolocalización: navigator.geolocation.getCurrentPosition(...)
- Notificaciones push: Notification.requestPermission(...)
- Cámara: navigator.mediaDevices.getUserMedia(...)
- Se puede encontrar toda la documentación de las APIs web y los permisos, si se necesitan, en el portal MDN web docs de Mozilla.
- Desde la salida de iOS 13, el usuario puede configurar, entre otros, los permisos que da a cada página web de manera individual:
- Permisos de acceso a hardware: cámara, micrófono, GPS, etc.
- Bloqueo de contenidos
- Carga de la web en formato móvil o escritorio
- Por lo tanto, la aplicación debe estar preparada para actualizar su comportamiento, teniendo en cuenta que los permisos concedidos o denegados inicialmente se pueden modificar en cualquier momento.
3.3.3. Gestión multiidioma
- R03.05.01 Las PWA, como mínimo, deben estar en catalán y castellano. También es recomendable que estén en inglés.
- R03.05.02 Las PWA deben utilizar el idioma por defecto del navegador y habilitar una función dentro de la PWA que permita cambiar entre los diferentes idiomas. En caso de no coincidir con ninguno de los idiomas disponibles, la PWA se ejecutará en catalán, con la posibilidad de cambiar manualmente. El cambio será automático y no puede suponer un reinicio de la PWA.
3.3.4. Calidad
- R03.06.01 Antes de ser publicadas, todas las PWA deberán ir acompañadas del plan de pruebas correspondiente para que la OSAM, durante su proceso de revisión, pueda validar el correcto funcionamiento de la PWA, y evidencias de que se ha hecho un juego de pruebas suficiente.
- R03.06.02 El proveedor deberá entregar el resultado de este plan de pruebas realizado en cada versión, con el objetivo de validar la corrección de la versión.
3.3.5. Experiencia de usuario
Las PWA tienen un objetivo claro que es dar a las webs una experiencia de usuario muy cercana a la de las aplicaciones nativas. Para lograr esto se trabaja en el rendimiento (velocidad de carga y respuesta), la tolerancia a fallos y la usabilidad.
- Rendimiento: el tiempo de carga de la aplicación debe ser controlado y reducido al máximo para no dar la sensación de estar bloqueada y hacer que el usuario tenga a su alcance la información o, como mínimo, una interfaz de usuario cargada.
- R03.07.01 Seguir las recomendaciones del módulo RAIL de Google.
- R03.07.02 La página principal (index.html) debe contener el CSS y JS mínimo inline para poder mostrar colores de fondo y de fuente sin esperar a la carga de recursos externos. Esto es lo que se llama application shell.
- R03.07.03 Los mensajes de carga (o imágenes) deben estar disponibles desde el principio. Se recomienda el uso de imágenes SVG inline para evitar la espera de carga de recursos externos.
- Tolerancia a errores: las aplicaciones deben estar preparadas para situaciones como la falta de conectividad a Internet y la caída (o inaccesibilidad) del servidor remoto.
- R03.07.04 Se debe evitar la página en blanco, los errores 404 o los mensajes de error automáticos por falta de conectividad. Las notificaciones al usuario deben seguir normas de usabilidad y diseño, como se especifica en el siguiente apartado.
- R03.07.05 Usabilidad: el usuario debe tener al principio una interfaz de usuario mínima que le indique que la aplicación ha cargado o está a punto de hacerlo:
- Color de fondo de la aplicación
- Cabeceras y pies de página
- Indicadores de carga (spinners, dialogs, etc.)
- Pantallas de error amigables y mensajes de error comprensibles: falta de conexión, el servidor no está accesible, problema con el dispositivo, etc.
- Siempre hay que seguir la guía de estilos donde aplique.
- R03.07.06 Instalación: la aplicación detectará cuando se encuentra ejecuándose dentro de un navegador para sugerir al usuario la instalación como una aplicación de escritorio.
- En dispositivos Android, en Chrome, el propio navegador muestra un dialog para recomendar al usuario que instale la PWA como una aplicación de escritorio.
- En el caso de iOS, en cambio, sobre Safari, se tendrá que mostrar una notificación personalizada, en el idioma que corresponda, indicando como lo debe de hacer el usuario para instalar la PWA. Para este propósito, se ofrece el siguinte snippet de código para detectar esta situación:
/* ************************** *
* ***** BROWSER RULES ****** *
* ************************** */
const BROWSER = {
chrome: /CrMo|CriOS|Android.*Chrome\/[.0-9]* (Mobile)?/,
safari: /Version.*Mobile.*Safari|Safari.*Mobile|MobileSafari/,
};
// User Agent
function _ua() {
// @ts-ignore
return window.navigator.userAgent || window.navigator.vendor || window.navigator.opera;
}
// Detects if device is on iOS
function isIos() {
const userAgent = _ua();
return /iphone|ipad|ipod/.test(userAgent.toLowerCase());
}
/* ************************** *
* ******** BROWSERS ******** *
* ************************** */
function isChrome() {
const userAgent = _ua();
return BROWSER.chrome.test(userAgent);
}
// Detects if browser is Safari
function isSafari() {
const userAgent = _ua();
// Chrome refers to Safari in its UA
return BROWSER.safari.test(userAgent) && !isChrome();
}
// Detects if device is in standalone mode (installed PWA)
function isInStandaloneMode() {
const isStandalone = window.matchMedia('(display-mode: standalone)').matches;
// @ts-ignore
return isStandalone || window.navigator.standalone;
};
/* ************************** *
* ****** SUGGESTIONS ******* *
* ************************** */
// Checks if should display install popup notification:
export function shouldSuggestIosInstallation() {
return isIos() && isSafari() && !isInStandaloneMode();
}
// Checks if should display 'open in Safari' notification:
export function shouldSuggestSafari() {
return isIos() && !isSafari() && !isInStandaloneMode();
}