3. Requeriments generals
3.1. Requeriments tècnics
3.1.1. Gestió del codi font, distribució i publicació
- R02.01.01 Les PWA publicades per l’Ajuntament són propietat d’aquest i, per tant, caldrà proporcionar el codi font i tot el material necessari un cop publicat el projecte. El codi font haurà de quedar correctament publicat a la branca del GitLab que es proporcionarà des de l'OSAM.
- R02.01.02 Per defecte qualsevol recurs que necessitin les PWA (fitxers de configuració, arxius, imatges, servidor d’aplicacions/web,...), haurà d’estar instal·lat a servidors de l’IMI o Ajuntament. En el cas que no es consideri possible caldrà justificar-ho a l'OSAM de forma prèvia i serà necessària la seva aprovació.
- R02.01.03 Les noves PWA que es creïn hauran de poder ser publicades sota una llicència OpenSource per part de l’Ajuntament. En cas de no ser possible o tenir inconvenients, cal parlar-ho amb l’OSAM per acordar una solució. Abans de començar el projecte, cal que l’equip de desenvolupament es posi en contacte amb l’OSAM per acordar el tipus de llicència.
- R02.01.04. Desenvolupament. Durant el procés de desenvolupament el proveïdor haurà d’utilitzar exclusivament les seves credencials, claus i recursos propis diferents als de producció, per totes aquelles eines externes tals com la Key d’Analytics, Firebase i Google Maps.
- R02.01.05. Publicació. Mentre que per les versions de producció s’utilitzaran les credencials, claus i recursos propis de l’OSAM. Aquests codis es facilitaran al proveïdor per tal que els introdueixi al codi font abans de publicar el projecte. En demanar la primera publicació de la PWA, s’haurà de tenir en compte que les PWA de l’Ajuntament de Barcelona es publicaran sempre seguint el següent patró d’URL: https://webapp.barcelona.cat**_/<nom_del_projecte>.
- L'aprovació de la URL concreta i la seva creació caldrà fer-ho mitjançant una petició a l'OSAM o a la Direcció de Comunicació Digital de l'Ajuntament.
3.1.2. Disseny Visual
- R02.02.01 Les PWA desenvolupades per a l’Ajuntament de Barcelona cal que segueixin la guia d’estil definida a tal efecte per la Direcció de Comunicació Digital.
3.1.3. Política d’ús de llibreries, eines i continguts de tercers
S'ha de complir el requeriment que les noves PWA puguin ser publicades sota una llicència OpenSource.
- R02.03.01 En cas d’utilitzar mapes cal garantir la normativa d’ús vigent, utilitzant sempre la darrera versió disponible del sistema.
- R02.03.02 Les PWAs no poden tenir materials amb drets d’autor o propietat de tercers (incloent-hi música, fotografies, vídeo, escultures, pintures i altres obres d’art o imatges publicades en llocs web o en la televisió, pel·lícules o altres mitjans) sense la corresponent cessió dels drets d’explotació de forma expressa i per escrit.
- R02.03.03 La plataforma obligatòria per trackejar l’ús de la PWA serà Google Analytics.
- R02.03.04 Es recomana l’ús de la plataforma Google Firebase per tal de complir amb les recomanacions de desenvolupament de les PWAs.
3.1.4. Analítica i feedback d’usuari
Google Analytics: Les analítiques i mètriques es faran amb Google Analytics de manera transparent gràcies al mòdul comú Core.js. Veieu secció 3.2.1 Core.js per obtenir informació de com configurar i fer servir la llibreria per al marcatge d’analítiques.
- R02.04.01 Enregistrament de dades. La PWA ha d’enregistrar com a mínim les pantalles visualitzades a la PWA com esdeveniments obligatoris. S’ha d’enregistrar l’esdeveniment de canvi d’idioma, identificat mitjançant un label amb un codi de dos lletres, segons l'idioma ISO corresponent (ex.CA, ES, EN, FR,...).
- R02.04.02 Seguiment de dades sense connexió. S'ha de fer servir el service worker que ofereix el paquet Workbox de Google, d'aquesta manera evitem que en un entorn sense connexió a internet, els accessos a Google Analytics amb el seguiment d'events fallin i es perdin les mesures d'aquest període. Més informació aquí.
3.1.5. Informes d’errors
- R02.05.01 Les aplicacions han d'integrar eines per a la detecció i informe d'errors d'execució un cop estiguin publicades a producció. Per a aplicacions web s'identifiquen diferents eines:
- Sentry és una de les eines més utilitzades per les grans companyies per a la generació d'informes d'errors de les aplicacions publicades. S'integra fàcilment amb multitud de frameworks frontend, backend i natius, així com eines de gestió de projecte com Jira i gestors de codi.
- El suport de Google Analytics per al seguiment d'errors es mínim, però es pot integrar igualment per a tenir aquesta informació també als dashboards.
- Airbrake és també una potent eina per al seguiment d'informes d'error, amb integracions amb molts llenguatges i frameworks de desenvolupament. Tanmateix es pot integrar fàcilment amb eines de gestió de projecte i de control de codi.
- Raygun disposa d'un projecte anomenat Crash Reporting. Es pot integrar fàcilment amb frameworks de frontend, i novament es pot integrar amb eines de gestió de projecte i control de codi.
- Rollbar és una suite per al seguiment d'errors és Rollbar. Com la resta, es pot fer servir fàcilment amb diferents frameworks frontend i eines de gestió de projecte i control de codi.
- Countly, dins el seu ecositstema d'analítiques per la web, ofereix plugins d'informes d'errors.
3.1.6. Versionat
- R02.06.01 Cal que les PWA de l'Ajuntament s'actualitzin correctament en segon pla quan es detecten canvis al sevidor (mitjançant el service worker).
- R02.06.02 Semantic versioning. Les PWA han d'incloure control de versions per fer la traçabilitat de quina versió està executant l'usuari. El número de versió ha seguir l'estàndard semver, que divideix la versió en tres números separats per punts: <major>.<minor>.<patch>, on:
- major: número de versió que s’incrementa cada cop que es fa una actualització no retrocompatible, o per motius comercials (denotar una gran actualització o remodelació).
- minor: número de revisió que inclou canvis retrocompatibles amb versions anteriors.
- patch: canvi menor per a solventar bugs i que no inclou cap nova funcionalitat.
- Per tant, el número de versió s’ha de modificar amb cada publicació de l’app actualitzant-lo d’acord amb els canvis que conté i segons el conveni descrit anteriorment. Cal verificar que la PWA s’actualitza correctament en segon pla quan es detecten els canvis al servidor (mitjançant el service worker).
- R02.06.03 Data de publicació Al número de la versió resultant se li afegirà al final una marca temporal, per identificar fàcilment la data de publicació, en format YYYYMMDD.
- Per exemple:
- Versió: 1.0.0_20190814
- S'identifica com la vresió 1.0.0 publicada el 14 d'agost de 2019.
- Per exemple:
- R02.06.04 Visibilitat del número de versió. El número de versió actual de la PWA ha de ser visible per a l’usuari final a la pantalla d’ajuda, seguint les especificacions de la guia d’estils: tamany i color de lletra discrets i no emfatitzats, ja que es tracta d’una informació útil però no relacionada amb els continguts de l’aplicació.
3.1.7. Auditoria Lighthouse
R02.07.01 Tota PWA haurà de complir amb un mínim del 80% de rendiment a l’auditoria de Lighthouse (Chrome developer tools).
3.2. Llibreries de l’Ajuntament
L’Ajuntament de Barcelona disposa d’eines desenvolupades internament que faciliten la homogeneïtat i la qualitat d’algunes funcionalitats.
A continuació es detallen aquelles que s’han considerat per a ser emprades a les noves PWA.
3.2.1 Core.js
Core.js es composa d’una fulla d’estils CSS i una llibreria JavaScript que, entre d’altres, proporcionen les següents funcionalitats que es poden fer servir de manera independent i opcional:
- Compliment de la normativa d’informació d’ús de cookies i l’acceptació (parcial o total) o negació per part de la persona usuària
- Tracking a Google Analytics de tots els clicks fets als enllaços (anchor) de la pàgina
Instal·lació
Afegir al document index.html les dependències de CSS i 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>
Funcionalitats requerides
- R02.08.01: Notificació d’ús de cookies i gestió per part de la persona usuària
<script type="application/javascript">
bcn.cookiescontrol();
</script>
- R02.08.02: Marcatges 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 cop que es modifiqui el DOM de la PWA (canvis de pantalla, aparició de nou contingut), s’haurà d’invocar novament la funció bcn.statistics per tal que Core.js afegeixi els gestors d’esdeveniments adients. Implícitament aquesta funció enviarà un marcatge de pàgina visitada (pageview), motiu pel qual és important cridar-la només un cop a cada re-render per evitar marcatges duplicats.
L’atribut de configuració test s’ha d’informar de la següent manera:
- Entorns no productius (DEV/UAT/...): valor true
- Entorn productiu (PRO): valor false o bé no informar aquest atribut.
Personalització de l’aparença
La notificació d’ús de cookies que genera el Core.js té una aparença totalment corporativa seguint els estils fixats per les webs de l’Ajuntament. A les PWA, però, el disseny pot ser totalment diferent, motiu pel qual es pot voler ajustar aquesta notificació per tal que s’integri visualment amb la resta de l’aplicació.
Per aconseguir això caldrà crear una fulla d’estils CSS on es redefineixin colors, fonts, transformacions de text, etc.
A continuació apareix una fulla SCSS que modifica la notificació per tenir una aparença més propera 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ó original:
Notificació resultant d’aplicar els nous estils:
3.3. Requeriments Funcionals
- Splash screen:
- R03.01.01 Es recomana que es presenti un mínim de 2 segons al iniciar la PWA.
- R03.01.02 En el cas de que el splash screen tingui alguna animació o just després que hi hagi alguna animació tipus carrusel de fotos, cal realitzar una de les següents accions:
- Passats 5 segons la PWA vagi a la home sense que la persona usuària faci res
- Que la pantalla tingui una indicació similar a “toca la pantalla per iniciar la PWA”
- R03.01.03 S'ha de seguir la guia d'estils referenciada a la secció 3.1.2 Disseny Visual
- Les splash screen no funcionen a iOS entre les versions 8 i 11.2 per un bug del sistema operatiu resolt a la versió 11.3.
- Icona:
- R03.01.04 És requerit afegir tantes resolucions d'icona com sigui necessari per donar suport a les diferents resolucions dels dispositius mòbils Android i iOS.
- R03.01.05 Entre les resolucions indicades anteriorment, s'ha de referenciar una icona de 192x192 píxels.
- R03.01.06 S'ha de seguir la guia d'estils referenciada a la secció 3.1.2 Disseny Visual
- R03.01.07 Cal especial és la icona adaptativa d'Android que va aparèixer amb la versió 8.0. El suport a aquest tipus d'icona es va introduir al manifest de les PWA el setembre de 2018 com a "maskable icon".
- Cal incloure un apartat d’ajuda per a les persones usuàries de fàcil accés a totes les PWAs. Com a mínim contindrà:
- R03.01.08 Descripció de l’app, objectius i apartats
- R03.01.09 Autoria del projecte
- R03.01.10 Número de versió de la PWA (agafant-lo dinàmicament del codi).
- R03.01.11 Caldrà indicar si la versió de la PWA està funcionant en un entorn de Pre-producció o Producció, on el primer és un entorn de proves.
- R03.01.12 Si la PWA està oberta, al fer clic de nou en la icona cal obrir-la en el punt que es trobava, i no pas arrencar-la de nou.
- R03.01.13 Si la PWA requereix descarregar un volum de dades “onfly” superior a 20mb, caldrà informar prèviament a l’usuari amb un missatge advertint la situació, donant la possibilitat de no fer-ho (explicant les conseqüències) i recomanant l’ús de wifi. Si és possible pel bon funcionament de la PWA, aquesta descarrega d’informació es faria en segon pla.
3.3.1. Consideracions per plataforma
Tot i tenir una especificació clara, les PWA no s’executen en un entorn homogeni entre plataformes natives. Apple per exemple, com a sistema propietari molt tancat, afegeix restriccions de memòria i emmagatzematge que s’ha de tenir present:
- Cicle de vida de l’aplicació
- Limitacions dels service workers
- Limitacions d’APIs
- Limitacions d’espai d’emmagatzematge
Microsoft té un gran suport per a PWA amb Windows 10, fins i tot les incorpora dins el seu Microsoft Store perquè les persones usuàries les puguin trobar fàcilment. A la seva documentació es llista el suport actual a les funcionalitats i APIs per les PWA.
R03.02.01 Tenir present les actualitzacions periòdiques de cada sistema operatiu per tal de ser compatibles amb les darreres dues versions del navegador predeterminat de cada plataforma, éssent aquest navegador Safari en iOS i Chrome en Android.
Es recomana l'ús i seguiment del suport natiu a les diferents APIs i novetats de W3C amb la web Can I use, per exemple: https://caniuse.com/#search=pwa
3.3.2. Privacitat i protecció de dades
RGPD
Les apps de l'Ajuntament de Barcelona han de complir amb la normativa vigent sobre protecció de dades i privacitat de les persones usuàries. En concret hauran de tenir en compte a nivell europeu el Reglament General de Protecció de Dades (2016/679) i a nivell estatal la Llei Orgànica de Protecció de Dades i Garantia de Drets Digitals (LO 3/2018 de 5 de desembre).
Atès que l'afectació d'aquestes normatives va més enllà del propi funcionament de les apps, la responsabilitat sobre la correcta aplicació d'aquestes és del responsable o promotor de l'aplicació. Tot i això, i sense menysteniment de la total aplicació d'aquestes normatives, a continuació enumerem alguns dels requeriments que caldrà tenir en compte en relació a aquestes i que seran validats per l'OSAM:
- R03.03.01 Quan es guardin, utilitzin o es moguin dades personals s'ha de sol·licitar i rebre el consentiment explícit i inequívoc de la persona usuària per poder procedir. Al inicialitzar-se l'app es mostrarà una pantalla en la qual es sol·licitarà aquest consentiment a la persona usuària i mitjançant una sèrie de missatges que li sol·liciten permisos aquest ha d'acceptar. Si no s’accepten aquestes condicions de servei la app mostrarà un missatge informant-lo i la funcionalitat quedarà amagada, per lo qual s'ha de validar que aquests permisos estan informats.
- R03.03.02 Per totes les apps que tinguin condicions d'acceptació de servei, s'ha de preveure que aquestes condiciones poden canviar. Per tant, hi ha d'haver un mecanisme que permeti forçar a acceptar aquestes condicions quan canviïn, tornant a mostrar la pantalla en la qual es sol·licita el consentiment a la persona usuària mostrant les noves condicions.
- R03.03.03 Una vegada la persona usuària ha acceptat les condicions del servei, la pantalla en la que es sol·licita el seu consentiment no tornarà a aparèixer, a menys que les condicions d'acceptació canviïn.
- R03.03.04 La informació personal de les persones usuàries s'encriptaran amb algoritmes robustos per minimitzar l'afectació de bretxes en la seguretat. Pel mateix motiu, les comunicacions amb servidors s'hauran de realitzar sota el protocol HTTPS.
Gestió de permisos
- R03.04.01 S'ha de tenir en compte que les aplicacions, i les seves actualitzacions, han d'implementar la gestió de permisos "on demand", és a dir, es demanaran a mesura que ho necessiti l’app no a l’inici o en un moment que per context no es pugui entendre per què necessita concedir aquest permís.
- R03.04.02 Sempre que estigui disponible al navegador, es farà l'ús de l'API Permissions per consultar els permisos concedits per a la persona usuària a l'aplicació per accedir a funcionalitats natives.
- Per tal de demanar permisos es faran servir els mètodes específics de cada API:
- Geolocalització: navigator.geolocation.getCurrentPosition(...)
- Notificacions push: Notification.requestPermission(...)
- Càmera: navigator.mediaDevices.getUserMedia(...)
- Es pot trobar tota la documentació de les APIs web i dels permisos, si calen, al portal MDN web docs de Mozilla.
- Des de la sortida d’iOS 13 l’usuari pot configurar, entre d’altres, els permisos que dóna a cada pàgina web de manera individual:
- Permisos d’accés a hardware: càmera, micròfon, GPS, etc.
- Bloqueig de continguts
- Càrrega del web en format mòbil o escriptori
- Per tant, l’aplicació ha d’estar preparada per actualitzar el seu comportament tenint en compte que els permisos concedits o denegats inicialment es poden modificar en qualsevol moment.
3.3.3. Gestió multiidioma
- R03.05.01 Les PWA, com a mínim, han d’estar en català i castellà. També és recomanable que estiguin en anglès.
- R03.05.02 Les PWA han d’utilitzar l’idioma per defecte del navegador i habilitar una funció dintre de la PWA que permeti canviar entre els diferents idiomes. En cas de no coincidir amb cap dels idiomes disponibles, la PWA s’executarà en català, amb la possibilitat de canviar-lo manualment. El canvi serà automàtic i no pot suposar un reinici de la PWA.
3.3.4. Qualitat
- R03.06.01 Abans de ser publicades, totes les PWA hauran d'anar acompanyades del pla de proves corresponent perquè l'OSAM, durant el seu procés de revisió, pugui validar el correcte funcionament de la PWA, i evidències de que s’ha fet un joc de proves suficient.
- R03.06.02 El proveïdor haurà d'entregar el resultat d'aquest pla de proves realitzat a cada versió, amb l'objectiu de validar la correctesa de la versió.
3.3.5. Experiència d’usuari
Les PWA tenen un objectiu clar que és donar a les webs una experiència d’usuari molt propera a la de les aplicacions natives. Per a aconseguir això s’hi treballa en el rendiment (velocitat de càrrega i resposta), la tolerància a errors i la usabilitat.
- Rendiment: el temps de càrrega de l'aplicació ha de ser control·lat i reduït al màxim per tal de no donar la sensació d'estar bloquejada i fer que l'usuari tingui al seu abast la informació o, com a mínim, una interfície d'usuari carregada.
- R03.07.01 Seguir les recomanacions del model RAIL de Google.
- R03.07.02 La pàgina principal (index.html) ha de contenir el CSS i JS mínim inline per a poder mostrar colors de fons i de font sense esperar a la càrrega de recursos externs. Això és el que s'anomena application shell.
- R03.07.03 Els missatges de càrrega (o imatges) han d'estar disponibles de bon començament. Es recomana l'ús d'images SVG inline per a evitar l'espera de càrrega de recursos externs.
- Tolerància a errors: les aplicacions han d'estar preparades per a situacions com la manca de connectivitat a Internet i la caiguda (o inaccessibilitat) del servidor remot.
- R03.07.04 S'ha d'evitar la pàgina en blanc, els errors 404 o els missatges d'error automàtics per manca de connectivitat. Les notificacions a l'usuari han de seguir normes d'usabilitat i disseny, com s'especifica al següent apartat.
- R03.07.05 Usabilitat: la persona usuària ha de tenir de bon començament una interfície d'usuari mínima que l'indiqui que l'aplicació ha carregat o està a punt de fer-ho:
- Color de fons de l'aplicació
- Capçaleres i peus de pàgina
- Indicadors de càrrega (spinners, dialogs, etc.)
- Pantalles d'error amigables i missatges d'erro entenedors: manca de connexió, el sevidor no està accessible, problema amb el dispositiu, etc.
- Sempre s'ha de seguir la guia d'estils allà on apliqui.
- R03.07.06 Instal·lació: l’aplicació detectarà quan es troba executant-se dins d’un navegador per suggerir a la persona usuària la instal·lació com a aplicació d’escriptori.
- A dispositius Android, en Chrome, el propi navegador mostra un dialog per recomanar l’usuari que instal·li la PWA com a aplicació d’escriptori.
- En el cas d’iOS en canvi, sobre Safari, s’haurà de mostrar una notificació personalitzada, en l’idioma que correspongui, indicant com ho ha de fer l’usuari per instal·lar la PWA. Per aquest propòsit, s’ofereix el següent snippet de codi per detectar aquesta situació:
/* ************************** *
* ***** 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();
}