R1. Requeriments generals

INDEX
R1.1. Gestió del codi font, distribució i publicació	R1.9. Versionat
R1.2. Disseny visual	R1.10.Rendiment
R1.3. Privacitat i protecció de dades	R1.11. Qualitat
R1.4. Política d'ús de llibreries, eines i contingut de tercers	R1.12. Accessibilitat
R1.5. Analítica, crashes i notificacions push	R1.13. Política d'integració amb xarxes socials
R1.6. Requeriments funcionals	R1.14. Integració cartografia municipal
R1.7. Mòduls de la OSAM	R1.15. Documentació
R1.8. Gestió multidioma

R1.1. Gestió del codi font, distribució i publicació

R1.1.1. Les aplicacions publicades per l’Ajuntament són propietat d’aquest i, per tant, caldrà proporcionar el codi font d’aquestes i tot el material necessari per a la seva distribució, publicació i manteniment.
R1.1.2. Per defecte qualsevol recurs que necessitin les apps (fitxers de configuració, arxius, imatges, servidor d’aplicacions/web,...), haurà d’estar instal·lat a servidors de l’IMI i gestionat per l’OSAM. En el cas que no es consideri possible es comunicarà a l’OSAM per acordar la millor solució.
- En fase de disseny i prototipatge de l'aplicació, els dissenys hauran de ser entregats amb una eina que permeti l'accés, ja sigui de llicència lliure o amb llicència o accés que faciliti el proveïdor, i en un format que permeti obtenir, de forma inequívoca, els codis de color de cadascun dels elements.
- En el cas que el disseny inclogui components (botons, selectors, menús, carosuels, etc.) amb unes funcionalitats fetes a mida (és a dir, que no estiguin basats en elements nadius) caldrà especificar en la mateixa eina de disseny o en un document a part com serà exactament aquesta funcionalitat i quines modificacions es preveuen fer.
R1.1.3. Les noves aplicacions que es creïn es recomana que puguin ser publicades sota una llicència OpenSource per part de l’Ajuntament. En cas que sigui així, 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.
R1.1.4. Desenvolupament. Per a nous desenvolupaments s'haurà d'utilitzar Flutter, ja que és el framework que l'OSAM recomana utilitzar per a nous desenvolupaments, al ser la tecnologia escollida per l'Ajuntament com a eina de desenvolupament per ser la que millor s'adapta a les seves necessitats: qualitat, complexitat, velocitat i cost del desenvolupament. Es poden consultar els requeriments específics de l'Ajuntament per desenvolupar en Flutter en: R4. Requeriments específics Flutter
- En cas que es vulgui usar un altre framework caldrà que prèviament es justifiqui i sigui aprovat per part de la OSAM.
- Per aquest motiu l'OSAM proporciona plugins a Flutter per poder usar les llibreries i mòduls comuns que desenvolupa. Si s'utilitza un altre framework, és responsabilitat del proveïdor generar els plugins necessaris per poder utilitzar aquestes llibreries i mòduls comuns.
- R1.1.4.1. Durant el procés de desenvolupament el proveïdor haurà d’utilitzar les seves credencials, claus i recursos propis com són, per exemple: Bundle ID per IOS, package per Android, Keys de Firebase, keys d’Analytics, key de Google Maps, etc. Aquests recursos són diferents als de Producció, que seran informats durant el procés de publicació per l'OSAM.
R1.1.5. Distribució. Per tal de facilitar la distribució de les aplicacions pel seu test durant el període de desenvolupament, es demana l’ús d’una plataforma que permeti, en el cas d’iOS, la distribució sense necessitat d’ús d’iTunes, ni consultar l'UDID del dispositiu per part de la persona usuària.
- Com a exemple; de sistema amb aquestes característiques es pot utilitzar Firebase App Distribution, dins la consola de Firebase (https://console.firebase.google.com/).
- Aquesta distribució la gestionarà el proveïdor.
- En el cas de les aplicacions que tinguin necessitats especials, s'ha de consultar amb l'OSAM al respecte.
  - Tant per la distribució interna dins l’OSAM com amb els proveïdors i persones responsables l’eina oficial serà Firebase App Distribution.
R1.1.6. Publicació.
- R1.1.6.1. Per la publicació de les aplicacions són necessaris els següents recursos gràfics:
  - Totes les plataformes:
    - Icona de l'aplicació: Les seves dimensions són: 512x512
  - Android;
    - Captures de pantalla: Han de ser en format .png o .jpg. La seva nomenclatura ha de tenir el nom, idioma i número de la imatge seguint el següent format: nomImatge_AA_00.extensió (ex: nomref_es_01.png, nomref_ca_01.jpg). S'han d'incloure com a mínim 4 i un màxim de 8 imatges per cada idioma de l'app, amb una resolució mínima de 1080 px. La relació d'aspecte ha de ser 16:9 per a les captures de pantalla horitzontals (1920x1080px) i de 9:16 per a captures de pantalla verticals (1080x1920px).
    - Feature Graphic: Imatge de capçalera. Les seves dimensions són 1024x500 px.
  - iOS:
    - Captures de pantalla: Han de ser en format .png o .jpg. La seva nomenclatura ha de tenir el nom, idioma i número de la imatge seguint el següent format: nomImatge_AA_00.extensió (ex: nomref_es_01.png, nomref_ca_01.jpg). Per IOS és necessari incloure com obligatòries les captures de pantalla d’iPhone Plus, Iphone XS Max, i iPad Pro (un mínim de 1 i un màxim de 10 captures de pantalla per dispositiu), repetint això per cada idioma de l'app (és a dir, per una app en català i castellà, s'hauran d'incloure com a mínim 6 imatges). Les seves dimensions són les següents:
      - iPhone amb pantalla de 5,5": Alçada 2208px, amplada 1242 px
      - iPhone amb pantalla de 6,5": Alçada 2688 px, amplada 1242 px
      - iPad amb pantalla de 12,9": Alçada 2732 px, amplada 2048 px
- R1.1.6.2. Per tal d'agilitzar la compilació, totes les apps i actualitzacions han de ser compatibles amb la integració contínua de l'Ajuntament per iOS i Android. Al document manual integració continua per a proveïdors s'indiquen les passes a seguir, tant per configurar el projecte, com per pujar el codi al repositori Gitlab de l'Ajuntament.
- R1.1.6.3.
  - Les aplicacions per a mòbils de l’Ajuntament es publicaran en els comptes que aquest té en els diferents markets i que són gestionats per l’OSAM. Per tant, totes les claus, certificats i altres que es requereixin per a la publicació seran gestionades a través d’aquest compte. En cap cas es proporcionaran claus, certificats, usuaris i altra informació privada al desenvolupador.
  - Per a les versions de producció s’utilitzaran les credencials, claus i recursos propis de l’OSAM. En concret: Bundle ID per IOS, package per Android, Keys de Crashlytics, keys d’Analytics, key de Google Maps i fitxer de parametrització del control de versions. Aquests codis no es facilitaran al proveïdor i s’introduiran al codi font per part dels tècnics OSAM durant el procés de compilació.
    - És important que el proveïdor no utilitzi ni el Bundle ID ni el package per Android el seu compte dels markets.
- R1.1.6.4. Per tal de poder preparar correctament la publicació de l'app, la persona responsable ha d'informar al cap de projecte de l'OSAM previament a l'enviament a Palàntir si la publicació d'una nova versió serà full roll-out (si la nova versió es publicarà inicialment al 100% de les persones usuàries) o serà progressiva (és publicarà inicialment a un nombre petit de persones usuàries i progressivament va augmentant aquest nombre).

R1.2. Disseny visual

R1.2.1. Les apps desenvolupades per a l’Ajuntament de Barcelona cal que segueixin la guia d’estil definida a tal efecte. Podem definir tres tipus d’apps, les estàndard, les específiques i les de productes. Cadascuna d’elles disposarà de la seva pròpia guia d’estil, les quals es poden consultar en les següents webs:
- Estàndards: apps-estandard.pdf
- Específiques: apps-especific.pdf
- Productes: apps-producte.pdf
R1.2.2. Per evitar problemes de seguretat als camps de text on s’hagin d’introduir contrasenyes cal definir correctament les àrees com “textPassword” per Android i “texfield.secureTextEntry = true” per a IOS.

R1.3. Privacitat i protecció de dades

R1.3.1. 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 han 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 de la persona 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 cal tenir en compte en relació amb aquestes i que seran validats per l'OSAM:
  - 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. A l'inicialitzar-se l'app es mostrarà una pantalla en la qual es sol·licitarà aquest consentiment a la persona usuària mitjançant una sèrie de missatges a on li sol·liciten els permisos i que aquesta ha d'acceptar. Si no s’accepten aquestes condicions de servei l'app s'aturarà, per la qual cosa s'ha de validar que aquests permisos estan informats.
  - Per totes les apps que tinguin condicions d'acceptació de servei, s'ha de preveure que aquestes condiciones poden canviar. Per tant, ha d'haver-hi 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 mostrant les noves condicions.
  - Una vegada la persona usuària ha acceptat les condicions del servei, la pantalla en la qual es sol·licita el seu consentiment no tornarà a aparèixer, a menys que les condicions d'acceptació canviïn.
  - 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.
R1.3.2. Gestió de permisos: 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 pel context la persona usuària no pugui entendre perquè necessita concedir aquest permís. També es donarà l'explicació de per què és necessari aquest permís justament abans o en el mateix moment de demanar-ho.
- Per gestionar correctament les notificacions push en dispositius Android 13 o superiors, les aplicacions han de tenir com a targetSDK 33 o superior, i s'haurà d'afegir el permís POST_NOTIFICATIONS al AndroidManifest. Un cop oberta l'app, i en el moment que es trobi adequat segons les especificacions de cada app, s'haurà de mostrar un pop-up o pantalla indicant si vol activar les notificacions push i perquè rebrà notificacions. Si Accepta demanarem el permís de push, perquè l'usuari accepti rebre notificacions. Si Cancel·la, les notificacions quedaran bloquejades i l'app no les no rebrà.
- Si un permís és imprescindible per al funcionalment de l'app s'ha de deixar clar que és així a la persona usuària quan se li demani, i si aquesta no dona el permís s'ha de mostrar un missatge informatiu, explicant que donat que no s'ha concedit el permís no es pot seguir amb el funcionament de l'app, i tancar l'app. No es pot produir un crash ni tornar a demanar el permís fins que es torni a iniciar l'app.
- Si l'usuari ha denegat la concessió d'un permís, però torna a accedir a una funcionalitat o pantalla en què l'app li demanaria aquest permís, es mostrarà un petit missatge en una zona visible de la pantalla recordant a l'usuari que ha denegat el permís de l'aplicació i amb un botó de "Configuració" que al clicar-ho porti a la configuració de l'app per si vol canviar això i donar el permís. El text del missatge es mostrarà en l'idioma de l'app.

missatge de permís denegat

R1.4. Política d'ús de llibreries, eines i contingut de tercers

R1.4.1. A continuació enumeren alguns dels requeriments que cal tenir en compte amb la utilització de llibreries i/o contingut de tercers:
- En cas d’utilitzar mapes de Google o Apple cal garantir la normativa d’ús vigent per cadascuna de les plataformes, utilitzant sempre la darrera versió disponible del sistema.
- En cas de ser necessari la utilització d'una API Key de Google, aquesta no s'ha de posar hardcoded, sinó que s'ha d'amagar la key en variables d'entorn o codificar-la perquè no pugui ser visible en el codi font. Si l'API Key es guarda en fitxers, que aquests estiguin fora de l'arbre de codi de l'aplicació.
- Si s'utilitza alguna llibreria que requereixi pagament i/o tenir targeta de crèdit, s'ha de consultar amb l'OSAM prèviament al desenvolupament.
- L’aplicació no pot contenir materials amb drets d’autor 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.
- Si l’aplicació requereix, per part de les persones desenvolupadores, d’un compte en un tercer sistema (xarxes socials, Google Maps, notificacions push, videoconferència, etc.) l’OSAM serà qui proporcionarà les claus per aquest. Mai s’utilitzarà un compte propi del desenvolupador o del responsable de l'aplicació.
R1.4.2. En el cas d'utilitzar qualsevol framework multiplataforma com ara Flutter, IONIC, React Native o Xamarin, entre d'altres, a l'inici del projecte cal utilitzar les darreres versions estables dels mateixos. Quan s'entregui el codi s'haurà d'utilitzar com a mínim la penúltima versió estable dels frameworks.
R1.4.3. A continuació enumerem els requeriments relatius a la crida a serveis per part de les apps, ja sigui serveis de tercers o a serveis propis ubicats en un backend propi:
- Recomanem que les apps tinguin un sistema per deshabilitar les crides a serveis de tercers, de manera que si es detecta un error o es despublica l'app es garanteix que no es realitzen aquestes crides. Aquest sistema pot ser, per exemple, unes variables en el Remote Config de Firebase que permetin deshabilitar aquestes crides.
- Les apps hauran de tenir un sistema per deshabilitar l'accés al serveis ubicats en un backend propi. Per exemple, mitjançant la pròpia configuració del backend.

R1.5. Analitica, crashes i notificacions push

Firebase és una plataforma per al desenvolupament d'aplicacions mòbils que permet tenir analítica i gestionar els crashos i les notificacions push.

R1.5.1. Integració amb Firebase Analytics: Totes les apps publicades hauran d’integrar com a eina d’analítica Firebase Analytics:
- Composició i configuració de les eines:
  - Totes les apps publicades hauran d’utilitzar l'última versió estable del SDK de Firebase disponible en el moment de la seva incorporació al projecte.
  - Com en qualsevol altra eina de tercers, per les versions de producció s’utilitzaran els codis generats a partir dels comptes de l’OSAM. L’oficina facilitarà l’accés de lectura a Firebase tant al client com al proveïdor, si així ho requereixen.
- Enregistrament de dades:
  - L’aplicació ha d’enregistrar com a mínim al Screen Name de Firebase Analytics el nom de les pantalles visualitzades a l’aplicació, a més de deixar que el Screen class s'informi automàticament. Els noms de les pantalles hauran de ser clar i autoexplicatius, de manera que per només amb el nom ja es pugui saber a quina pantalla fa referència. Aquests noms han de ser iguals per totes les plataformes (Android e iOS).
  - S’ha d’enregistrar l’esdeveniment de canvi d'idioma, identificat mitjançant una variable amb el nom 'language_change'. Aquest esdeveniment s'enregistrarà el primer cop que s'iniciï l'app i també amb cada canvi d'idioma. L'esdeveniment tindrà tres paràmetres:
    - "previous_language": que informarà de l’idioma de l'app previ a realitzar el canvi d'idioma. Si s'està enregistrant l'esdeveniment el primer cop que s'inicia l'app, aquest paràmetre serà buit.
    - "selected_language": que informarà de l’idioma de l'app a l'iniciar l'app i una vegada es realitza el canvi d'idioma.
    - "language_disp": que registrarà l’idioma actual del dispositiu a l'iniciar l'app.
  - On l'idioma s'informarà mitjançant un label amb un codi de dues lletres, segons l'idioma ISO corresponent (ex.CA, ES, EN, FR,...)
- Durant la fase de desenvolupament:
  - El proveïdor haurà d’utilitzar els seus propis codis per tal de validar que el sistema d’analítica funciona correctament.
  - Els proveïdors hauran de proporcionar accés a OSAM per a consultar les estadístiques de desenvolupament per la seva validació prèvia.
R1.5.2. Integració amb Firebase Crashlytics: per poder gestionar els crashes de les aplicacions i informar el proveïdor d'aquests, s’ha d’incorporar a totes les aplicacions sobre l’eina de gestió de crashes, Firebase Crashlytics:
- L’OSAM proporcionarà la documentació necessària pera la integració i utilització d’aquesta eina, a més de donar l’ API KEY per incorporar al projecte. A la documentació oficial de Google, https://firebase.google.com/docs/crashlytics/get-started, podem veure com realitzar aquesta integració.
- Com en totes les eines de tercers utilitzades a l’OSAM, durant el desenvolupament el proveïdor utilitzarà crashlytics amb el seu propi compte i keys generades per ell. Si l’OSAM ho requereix caldrà donar-li accés de lectura.
- Firebase Crashlytics ha d’estar inicialitzat en la classe Application (Android).
- Quan l'app faci una crida a una API i es produeixi un error controlat, s'haurà de fer una crida a Crashlytics per registrar l'error com a Non-Fatal (o error recuperable) i les dades que siguin importants per diagnosticar l'error: traça amb la crida que ha realitzat, codi d'error que permeti identificar ràpidament el tipus d'error, i el text amb l'error retornat pel servidor. A continuació indiquem un enllaç a la documentació oficial de Firebase per registrar aquest tipus d'errors amb Flutter: https://firebase.google.com/docs/crashlytics/customize-crash-reports?platform=flutter
R1.5.3. Notificacions push: les notificacions push seran obligatòries per a totes les noves apps o actualització d’apps existents, i cal utilitzar la plataforma Firebase Cloud Messaging. Aquest requeriment és independent de què l'app tingui un altre sistema de notificacions push.
- Es recomana als proveïdors utilitzar la clau d'autenticació d'APNS, en la fase de desenvolupament de les seves apps iOS, per validar el funcionament de les notificacions push per mitjà de la consola de Firebase. Firebase recomana aquesta configuració i és el que per defecte utilitzarà l'OSAM en les aplicacions de producció.
- La notificació es mostrarà segons l’opció per defecte del sistema operatiu i la configuració de visualització triada, no caldrà fer cap adaptació addicional.
- Amb l'app en foreground es notificarà a la persona usuària mitjançant un pop-up.

notificació pop-up

Amb l'app en background es mostrarà en el toolbar:

notificació es mostra en el toolbar

La icona de la notificació haurà de ser representativa de l'app, essent recomanable que s'assembli a la icona del launcher.
Qualsevol altre customització és oberta als desenvolupadors, previ consens amb l'OSAM.
Si l’aplicació conté una opció de menú per consultar les notificacions, aquestes quedaran enregistrades quan es generin (si l’app està instal·lada) i les més recents es podran consultar en aquesta opció de menú. Si encara no han estat consultades es mostrarà un superíndex amb un número a sobre de la icona de l’app a l’escriptori del dispositiu (si està configurat per tal que es mostri el número). El número contindrà el nombre de notificacions pendents de consultar.

mostra número

Tòpics:
- Cal implementar un tòpic per poder enviar una notificació push a una versió determinada de l'app. Aquest tòpic ha de seguir la següent nomenclatura: nomApp_X.Y.Z_buildNumber per iOS i nomApp_X.Y.Z_versionCode per Android, i es realitzarà la subscripció en obrir l'app.
- S'ha d'utilitzar com a mínim un tòpic per cada idioma que tingui l'aplicació, identificats mitjançant una etiqueta amb un codi de dues lletres, segons l'idioma ISO corresponent (ex.CA, ES, EN, FR,...).
- En relació a aquests tòpics, l'aplicació ha d'estar subscrita únicament al tòpic referent al seu idioma actual, i en el cas de que la persona usuària canviï l'idioma de l'aplicació s'ha d'anul·lar aquesta subscripció i fer-ne una de nova al tòpic referent al nou idioma.
Han de ser visibles amb pantalla emergent, no només amb un avís tipus "campaneta".
Si calen funcionalitats addicionals que no proporciona Firebase s’ha de consultar amb l’OSAM per decidir la millor solució.
La gestió de les notificacions serà delegada a la persona responsable de l'aplicació, però serà la mateixa OSAM qui doni els permisos per poder realitzar aquesta gestió.

Per ajudar a solucionar els problemes que puguin aparèixer amb la integració amb Firebase, l'OSAM ha preparat el següent document on es descriuen problemes que s'han detectat i la seva solució.

R1.6. Requeriments funcionals

A més dels requeriments funcionals requerits per negoci, totes les apps de l’Ajuntament de Barcelona han de seguir els següents punts:

R1.6.1. El splash screen cal que es presenti un mínim de 2 segons a l'iniciar l’aplicació.
R1.6.2. La següent informació ha de ser d'accés fàcil i directe (sense necessitat d'estar registrat a l'aplicació o altre pas previ) a totes les aplicacions.
- Un apartat d’ajuda per a les persones usuàries i que com a mínim ha de tenir:
  - Descripció de l’app, objectius i apartats.
  - Un mètode de contacte amb l'Ajuntament. Si la persona responsable de l'aplicació no en proporciona un mitjançant el sistema de gestió d'incidències IRIS (Incidències, Reclamacions i Suggerències), s'ha d'indicar el mail mobil@bcn.cat. En el cas que es vulgui una altra opció, es comunicarà a l'OSAM per acordar la millor solució.
    - Al clicar en l'adreça electrònica, s'obrirà l'aplicació de correu per defecte del mòbil amb el destinatari informat, i cal que es mostri la següent informació:
      - Assumpte: "Contacte Nom Aplicació". Aquest text es mostrarà en el llenguatge de l'aplicació.
      - Cos del missatge: Informació del dispositiu i de l'app, amb un text informant a l'usuari que a continuació descrigui els seus motius per contactar. Aquest text es mostrarà en el llenguatge de l'aplicació. Per obtenir la informació del dispositiu i de l'app cal tenir instal·lat el mòdul comú de l'OSAM, com s'indica en aquest document al requeriment R1.7.
- Per aquelles apps on s'hagi realitzat un informe sobre accessibilitat, s'ha d'incloure un enllaç a la declaració d'accessibilitat. Aquest enllaç és proporcionat per l'OSAM.
- Autoria del projecte. Per defecte és "Ajuntament de Barcelona".
- Justificació de l’ús de dades. Es pot utilitzar el següent text com a model:
  - "L'aplicació XXXX es pot descarregar gratuïtament. El seu ús requereix d'una connexió de dades activa, ja sigui wifi o a través de la xarxa de telefonia". Afegir "Es recomana tenir activat el GPS" per als casos en què l'app tingui geolocalització.
- Número de versió de l'aplicació i el versionCode / build version, depenent de la plataforma (agafant-lo dinàmicament del binari)
- Cal indicar si la versió de l’aplicació està funcionant en un entorn de Pre-producció o Producció, on el primer és un entorn de proves.
R1.6.3. Si l’aplicació està oberta, al clicar de nou en la icona cal obrir-la en el punt que es trobava, i no pas arrencar-la de nou.
R1.6.4. Si l’aplicació requereix descarregar un volum de dades superior a 20MB, cal informar prèviament a la persona usuària 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 l’aplicació, aquesta descàrrega d'informació caldria fer-se en segon pla.
R1.6.5. En el cas que un url es vulgui mostrar dins l'app amb un webview intern, la pàgina corresponent ha d'estar optimitzada per ser mostrada dins l'app i, per tant, integrada amb el disseny i funcionament de l'app. Qualsevol enllaç que hi hagi dins d'aquesta pàgina ha de complir aquest mateix requeriment. Si es vol enllaçar a una pàgina que no compleixi aquest requeriment, cal obrir-la dins del navegador per defecte del sistema operatiu.
R1.6.6. Si una funcionalitat de l'aplicació implica com arribar a un destí, i aquesta et porta fora de l'app, cal indicar a la persona usuària la possibilitat de seleccionar entre les diferents aplicacions de navegació que té instal·lades en el seu dispositiu, delegant en el sistema operatiu aquesta selecció.

R1.7. Mòduls de la OSAM

Des de l'OSAM es proporcionen mòduls d'ús obligatori per la realització d'un conjunt de tasques comunes a totes les apps publicades per l'Ajuntament de Barcelona. Aquests mòduls són descarregables des de https://ajuntamentdebarcelona.github.io/ o https://github.com/AjuntamentdeBarcelona , essent obligatori descarregar sempre la darrera versió publicada.

Totes les apps de l’Ajuntament han d’incorporar el Mòdul comú (R1.7.1).

R1.7.1. Mòdul comú: aquest mòdul integra les següents funcionalitats: control de versions, control de valoracions i obtenció d'informació de dispositiu i aplicació.
- Control de versions: mostra, depenent del tipus de restricció, un pop up que informa i convida a la persona usuària a actualitzar-se l'app al market corresponent (GooglePlay o AppStore). L'objectiu és que no es pugui utilitzar l'app en cas d'estar activat.
- Control de valoracions: mostra, a partir d’una periodicitat i d’un nombre d'execucions, un pop up que convida a la persona usuària a valorar l’aplicació en el market place corresponent (GooglePlay o AppStore).
- Obtenció d'informació de dispositiu i aplicació: retorna informació del dispositiu, com model, versió de OS, versió de l'aplicació, etc.
Es pot consultar el manual del mòdul al fitxer README al Github.
Es pot descarregar el mòdul comú des de Github.
El comportament del mòdul comú es fa a temps real per l’OSAM en producció. En la fase de desenvolupament, el proveïdor podrà utilitzar un url de desenvolupament proporcionada per l'Ajuntament.
El control de versions s’ha de mostrar sempre a les apps de forma individual abans d’iniciar l'splash screen i cada cop que es passi de l'estat d'inactivitat a activitat (background -> foreground), tenint en compte que no s'han de fer altres crides o peticions abans de cridar aquest mòdul.

L'OSAM proporcionarà un manual on s'explica com, en un entorn de Desenvolupament, poder validar que el mòdul comú s'ha implementat correctament.

Flutter

Pel framework Flutter, l'OSAM disposa d'un plug-in que implementa la funcionalitat de la llibreria nativa.

Es pot descarregar el plug-in del mòdul comú des de Github.
Es pot consultar el manual del plug-in al fitxer README al Github.

Integrar el mòdul comú en aplicacions de frameworks diferents a Flutter

És responsabilitat del proveïdor integrar el mòdul comú amb altres frameworks diferents a Flutter. En el suposat que no sigui possible aquesta integració, i prèviament l'autorització de l'OSAM, el proveïdor ha d'implementar-ne un de propi amb les funcionalitats del mòdul comú, que ha de llençar events de Firebase que enregistrin quan es cridi al mòdul. Ho ha de comunicar a l'oficina, al cap de projecte de l'OSAM, explicant detalladament el seu funcionament i implementació, i en el test de proves que s'entrega en la publicació de l'app ha d'explicar com provar el correcte funcionament del mòdul.

R1.8. Gestió multidioma

R1.8.1. Les aplicacions, com a mínim, han d’estar en català i castellà, i és recomanable que també estiguin en anglès. Els idiomes disponibles han de coincidir amb els especificats en el codi font/binari i per tant, amb els que especificaran els corresponents markets.
R1.8.2. Han d’habilitar una funció dins l’aplicació, prèviament al registre de l’app, que permeti canviar entre els diferents idiomes. Aquest canvi ha de ser automàtic i no pot suposar un reinici de l’aplicació.
R1.8.3. Inicialment, les aplicacions han d’utilitzar l’idioma per defecte del dispositiu. En cas de no coincidir amb cap dels idiomes disponibles, l’aplicació s’executarà en anglès si aquest idioma està disponible en l'app o en català si no és així, amb la possibilitat de canviar-lo manualment.

R1.9. Versionat

El número de versió ha de seguir la següent nomenclatura:
- X – Versió major utilitzada per canvis funcionals importants
- Y – Versió menor utilitzada per a canvis funcionals petits, actualitzacions de dades o correcció d’incidències
- Z – Aquest número només variarà si hi ha diverses iteracions amb l’OSAM en el procés de publicació, o si es publica una versió urgent per solucionar un error greu.
Per apps noves, la primera versió que es publica ha de ser 1.0.Z, on Z dependrà del nombre d'iteracions que s'hagin realitzat un cop la versió s'ha entregat a l'OSAM. Per exemple, si la versió entregada s'ha publicat en producció directament sense detectar-se cap problema, seria 1.0.0. Si s'han hagut de realitzar dues versions correctives addicionals, llavors serà 1.0.2.

R1.10. Rendiment

Tota funcionalitat del sistema i transacció de negoci ha de respondre a la persona usuària en menys de 5 segons en el 90% de les peticions. S'ha de tenir en compte també la següent informació:

0.1 segons és el límit perquè la persona usuària senti que el sistema reacciona instantàniament, és a dir, que no es necessita cap retroalimentació especial, excepte per mostrar el resultat.
En les consultes que el temps sigui superior a 1 segon s'ha de mantenir l'atenció de la persona usuària ocupada amb un spinner, barra de progrés, etc.; un element que mostri que l'app està funcionant i no s'ha quedat bloquejada.
10 segons és el límit per mantenir l'atenció de la persona usuària centrada en l'app. En cas de superar-se aquest temps, cal produir un time out, cancel·lar la petició e informar a la persona usuària.

El procés d'arrancada (startup) no ha de superar els temps indicats en un 95% de les ocasions:

La cold startup triga 5 segons o més.
La warm startup triga 2 segons o més.
La hot startup triga 1.5 segons o més.

Es pot consultar la definició d'aquests termes a: Android Vitals

R1.11. Qualitat

R1.11.1. Totes les apps han d'anar acompanyades del pla de proves corresponent per què l'OSAM, durant el procés de testing intern del cicle de vida, pugui validar el correcte funcionament de l'aplicació, i evidències que s’ha fet un joc de proves suficient.
- El proveïdor ha d'entregar el resultat d'aquest pla de proves realitzat a cada versió, amb l'objectiu de validar la correctesa de la versió.
R1.11.2.
- L'OSAM ha definit uns criteris de qualitat de codi per a les apps. Aquests criteris s'han definit amb la eina SonarQube (https://www.sonarsource.com/products/sonarqube/), que utilitza l'OSAM en el procés de publicació, i són els següents:
  - Per al nou codi de la versió:
    - Línies duplicades no poden superar el 1% del codi
    - Manteniment del codi ha de ser millor que una B
    - Fiabilitat del codi ha de ser una A
    - No poden haver security hotspots sense revisar
    - La seguretat ha de ser una A. No poden haver bugs ni vulnerabilitats
  - Per al codi general de l'app:
    - Línies duplicades no poden superar el 3% del codi
    - Manteniment del codi ha de ser millor que una C
    - Fiabilitat del codi ha de ser una A
    - No poden haver security hotspots sense revisar
    - La seguretat ha der una A. No poden haver bugs ni vulnerabilitats.
- Durant el procés de publicació d'una app s'enviarà un mail amb l'anàlisi del codi. Si es vol veure amb més detall els resultats de l'anàlisi de les aplicacions es pot accedir al SonarQube de l'OSAM. Si no teniu accés, podeu demanar-lo enviant un correu electrònic a l'OSAM.
- És obligatori complir amb aquests criteris de qualitat de codi, i les apps que incompleixin algun dels criteris mencionants no es publicaran.

R1.12. Accessibilitat

El Reial Decret 1112/2018, sobre accessibilitat dels llocs web i aplicacions per a dispositius mòbils del sector públic i que és d'obligatori seguiment per a tots els organismes públics, estableix els condicionants, respecte a l'accessibilitat, que han de complir tots els llocs web i aplicacions mòbils del sector públic. En aquest sentit, les aplicacions han de ser accessibles seguint els criteris de la guia d’accessibilitat en aplicacions natives per a dispositius mòbils, actualitzada recentment amb els requisits WCAG 2.1.

Per facilitar la validació de l'accessibilitat d'una aplicació es recomana la utilització de les següents eines de Google, segons la plataforma:

Android: App a la PlayStore Test de Accesibilidad
iOS: Projecte al GitHub GSCXScanner

R1.13. Política d'integració amb xarxes socials

Si compartim un enllaç o una imatge en una xarxa social, aquest no ha de ser genèric d’una web, sinó que ha d'apuntar directament a la informació que es vol compartir. Per exemple, si estem a una aplicació que mostra un conjunt d’activitats i volem compartir una d’elles, l’enllaç hauria de portar a l’activitat concreta i no a una web genèrica de l’app.

R1.14. Integració cartografia municipal

R1.14.1. El framework oficial de mapes per les apps de l'Ajuntament és Mapbox, i per tant és d'ús obligatori per a aquelles apps amb àmbit territorial exclusiu a Barcelona. Tenint en compte aquesta restricció quant a l'àmbit territorial, s'han de complir els següents punts:
- Tota app nova ha d'integrar Mapbox i utilitzar la cartografia municipal de l'Ajuntament.
- Totes les actualitzacions de les apps de l'Ajuntament han d'integrar Mapbox i la cartografia municipal.
- Les apps de l'Ajuntament desenvolupades en Flutter poden utilitzar el següent plug-in per integrar Mapbox: https://pub.dev/packages/mapbox_maps_flutter. En la web de Mapbox es pot trobar la documentació oficial per integrar-ho tant per Android com per iOS.
R1.14.2. Cartografia municipal: per poder integrar la cartografia municipal de l'Ajuntament, l'OSAM posa a disposició pel desenvolupament el següent fitxer: https://osam.bcn.cat/apps/mapbox/bcn.json. Aquest json és comú per a totes les apps de l'Ajuntament i és d'ús obligatori.

R1.15. Documentació

És necessari que el projecte tingui un mínim de documentació.

R1.15.1. README: En el readme del projecte ha d'estar detallada la següent informació:
1. Requeriments per poder executar l'aplicación. Aquests seran la versió utilitzada per a construir l'aplicació (Android SDK, iOS, Flutter), configuració de Mapbox i altres requeriments si fos necessari.
2. Pasos per executar i construir el projecte.
3. Descripció dels entorns
R1.15.2. Notes de llançament: El fitxer release_notes.txt ha d'estar en la carpeta arrel del projecte. Haurà de contenir tots els canvis des del llançament de la darrera compilació i distribució. El format pot ser com una llista en la qual cada punt té la descripció de la funcionalitat.
R1.15.3. Changelog: En les apps noves, el fitxer changelog.md ha d'estar en la carpeta arrel del projecte. Haurà de contenir tots els canvis realitzats durant el projecte, separant-los per cada versió que s'hagi distribuit. Per poder automatizar la generació d'aquest fitxer es recomana utilitzar conventional commits (https://www.conventionalcommits.org/).