R1. Requeriments generals

R1. Requeriments generals

INDEX

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

R1.8. Gestió multidioma

R1.2. Disseny visual

R1.9. Versionat

R1.3. Privacitat i protecció de dades

R1.10. Rendiment

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

R1.11. Qualitat

R1.5. Analítica, crashes i notificacions push

R1.12. Accessibilitat

R1.6. Requeriments funcionals

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

R1.7. Mòduls de la OSAM

R1.14. Integració cartografia municipal

 

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 han 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.

  • 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.

    • 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 Plus: Alçada 2208px, amplada 1242 px

        • iPhone XS Max: Alçada 2688 px, amplada 1242 px

        • iPad Pro: 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. Les aplicacions Android que es vulguin publicar amb data posterior al 26 de juliol de 2021 hauran de seguir les instruccions respecte a App Bundle que hi ha en el Manual d'integració continua per a proveïdors.

    • 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.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.

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, cal utilitzar les darreres versions estables dels mateixos.

  • 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.

 

  • Amb l'app en background es mostrarà 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.

  • 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 cap, s'ha d'indicar el mail mobil@bcn.cat.

    • 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 i control de valoracions.

    • 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).

  • 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ó.

  • 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:

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.

    • A partir de l'1 de gener de 2023, 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_gl. 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.

Crear revisión: 
Revisió visible: 

Índex

R1. Requeriments generals

INDEX

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

R1.8. Gestió multidioma

R1.2. Disseny visual

R1.9. Versionat

R1.3. Privacitat i protecció de dades

R1.10. Rendiment

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

R1.11. Qualitat

R1.5. Analítica, crashes i notificacions push

R1.12. Accessibilitat

R1.6. Requeriments funcionals

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

R1.7. Mòduls de la OSAM

R1.14. Integració cartografia municipal

 

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 han 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.

  • 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.

    • 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 Plus: Alçada 2208px, amplada 1242 px

        • iPhone XS Max: Alçada 2688 px, amplada 1242 px

        • iPad Pro: 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. Les aplicacions Android que es vulguin publicar amb data posterior al 26 de juliol de 2021 hauran de seguir les instruccions respecte a App Bundle que hi ha en el Manual d'integració continua per a proveïdors.

    • 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.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.

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, cal utilitzar les darreres versions estables dels mateixos.

  • 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.

 

  • Amb l'app en background es mostrarà 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.

  • 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 cap, s'ha d'indicar el mail mobil@bcn.cat.

    • 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 i control de valoracions.

    • 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).

  • 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ó.

  • 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:

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.

    • A partir de l'1 de gener de 2023, 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_gl. 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.


Historical

• 21/06/2023 12:45

R1. Requeriments generals

R1. Requeriments generals

INDEX

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

R1.8. Gestió multidioma

R1.2. Disseny visual

R1.9. Versionat

R1.3. Privacitat i protecció de dades

R1.10. Rendiment

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

R1.11. Qualitat

R1.5. Analítica, crashes i notificacions push

R1.12. Accessibilitat

R1.6. Requeriments funcionals

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

R1.7. Mòduls de la OSAM

R1.14. Integració cartografia municipal

 

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 han 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.

  • 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.

    • 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 Plus: Alçada 2208px, amplada 1242 px

        • iPhone XS Max: Alçada 2688 px, amplada 1242 px

        • iPad Pro: 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. Les aplicacions Android que es vulguin publicar amb data posterior al 26 de juliol de 2021 hauran de seguir les instruccions respecte a App Bundle que hi ha en el Manual d'integració continua per a proveïdors.

    • R.1.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.2. Disseny visual

  • R1.2.2. A més de la guia d’estil, les aplicacions han de seguir els següents requeriments visuals:

    • Les aplicacions que disposin de la funcionalitat d’agregar a favorits/preferits, la icona ha de ser preferiblement una estrella per a unificar a nivell de totes les apps municipals. Si s’escau un altre ús cal consensuar-ho amb l’OSAM.

    • 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.

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, cal utilitzar les darreres versions estables dels mateixos.

  • 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.

 

  • Amb l'app en background es mostrarà 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.

  • 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 cap, s'ha d'indicar el mail mobil@bcn.cat.

    • 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 i control de valoracions.

    • 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).

  • 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ó.

  • 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 email a l'OSAM.

  • Actualment només es recomana que les versions entregades per la seva publicació compleixin aquests criteris de qualitats de codi, però a partir d'octubre del 2023 això serà un requeriment 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:

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.

    • A partir de l'1 de gener de 2023, 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_gl. 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.

• 31/05/2023 11:53

R1. Requeriments generals

R1. Requeriments generals

INDEX

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

R1.8. Gestió multidioma

R1.2. Disseny visual

R1.9. Versionat

R1.3. Privacitat i protecció de dades

R1.10. Rendiment

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

R1.11. Qualitat

R1.5. Analítica, crashes i notificacions push

R1.12. Accessibilitat

R1.6. Requeriments funcionals

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

R1.7. Mòduls de la OSAM

R1.14. Integració cartografia municipal

 

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 han 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.

  • 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.

    • 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 Plus: Alçada 2208px, amplada 1242 px

        • iPhone XS Max: Alçada 2688 px, amplada 1242 px

        • iPad Pro: 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. Les aplicacions Android que es vulguin publicar amb data posterior al 26 de juliol de 2021 hauran de seguir les instruccions respecte a App Bundle que hi ha en el Manual d'integració continua per a proveïdors.

    • R.1.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.2. Disseny visual

  • R1.2.2. A més de la guia d’estil, les aplicacions han de seguir els següents requeriments visuals:

    • Les aplicacions que disposin de la funcionalitat d’agregar a favorits/preferits, la icona ha de ser preferiblement una estrella per a unificar a nivell de totes les apps municipals. Si s’escau un altre ús cal consensuar-ho amb l’OSAM.

    • 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.

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, cal utilitzar les darreres versions estables dels mateixos.

  • 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.

 

  • Amb l'app en background es mostrarà 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.

  • 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 cap, s'ha d'indicar el mail mobil@bcn.cat.

    • 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 i control de valoracions.

    • 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).

  • 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ó.

  • 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 email a l'OSAM.

  • Actualment només es recomana que les versions entregades per la seva publicació compleixin aquests criteris de qualitats de codi, però a partir d'octubre del 2023 això serà un requeriment 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:

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.

    • A partir de l'1 de gener de 2023, 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_gl. 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.

• 30/03/2023 17:44

R1. Requeriments generals

R1. Requeriments generals

INDEX

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

R1.8. Gestió multidioma

R1.2. Disseny visual

R1.9. Versionat

R1.3. Privacitat i protecció de dades

R1.10. Rendiment

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

R1.11. Qualitat

R1.5. Analítica, crashes i notificacions push

R1.12. Accessibilitat

R1.6. Requeriments funcionals

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

R1.7. Mòduls de la OSAM

R1.14. Integració cartografia municipal

 

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 han 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.

  • 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.

    • 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 Plus: Alçada 2208px, amplada 1242 px

        • iPhone XS Max: Alçada 2688 px, amplada 1242 px

        • iPad Pro: 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. Les aplicacions Android que es vulguin publicar amb data posterior al 26 de juliol de 2021 hauran de seguir les instruccions respecte a App Bundle que hi ha en el Manual d'integració continua per a proveïdors.

    • R.1.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.2. Disseny visual

  • R1.2.2. A més de la guia d’estil, les aplicacions han de seguir els següents requeriments visuals:

    • Les aplicacions que disposin de la funcionalitat d’agregar a favorits/preferits, la icona ha de ser preferiblement una estrella per a unificar a nivell de totes les apps municipals. Si s’escau un altre ús cal consensuar-ho amb l’OSAM.

    • 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.

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, cal utilitzar les darreres versions estables dels mateixos.

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.

 

  • Amb l'app en background es mostrarà 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.

  • 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 cap, s'ha d'indicar el mail mobil@bcn.cat.

    • 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 i control de valoracions.

    • 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).

  • 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ó.

  • 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 email a l'OSAM.

  • Actualment només es recomana que les versions entregades per la seva publicació compleixin aquests criteris de qualitats de codi, però a partir del tercer trimestre del 2023 això serà un requeriment 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:

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.

    • A partir de l'1 de gener de 2023, 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_gl. 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.

• 29/03/2023 12:07

R1. Requeriments generals

R1. Requeriments generals

INDEX

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

R1.8. Gestió multidioma

R1.2. Disseny visual

R1.9. Versionat

R1.3. Privacitat i protecció de dades

R1.10. Rendiment

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

R1.11. Qualitat

R1.5. Analítica, crashes i notificacions push

R1.12. Accessibilitat

R1.6. Requeriments funcionals

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

R1.7. Mòduls de la OSAM

R1.14. Integració cartografia municipal

 

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 han 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.

  • 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.

    • 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 Plus: Alçada 2208px, amplada 1242 px

        • iPhone XS Max: Alçada 2688 px, amplada 1242 px

        • iPad Pro: 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. Les aplicacions Android que es vulguin publicar amb data posterior al 26 de juliol de 2021 hauran de seguir les instruccions respecte a App Bundle que hi ha en el Manual d'integració continua per a proveïdors.

    • R.1.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.2. Disseny visual

  • R1.2.2. A més de la guia d’estil, les aplicacions han de seguir els següents requeriments visuals:

    • Les aplicacions que disposin de la funcionalitat d’agregar a favorits/preferits, la icona ha de ser preferiblement una estrella per a unificar a nivell de totes les apps municipals. Si s’escau un altre ús cal consensuar-ho amb l’OSAM.

    • 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.

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, cal utilitzar les darreres versions estables dels mateixos.

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.

 

  • Amb l'app en background es mostrarà 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.

  • 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 cap, s'ha d'indicar el mail mobil@bcn.cat.

    • 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 i control de valoracions.

    • 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).

  • 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ó.

  • 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

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.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:

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.

    • A partir de l'1 de gener de 2023, 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_gl. 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.

Back to top