R1.Requisitos generales

INDEX
R1.1. Gestión del código fuente, distribución y publicación R1.9. Versionado
R1.2. Diseño visual R1.10. Rendimiento
R1.3. Privacidad y protección de datos R1.11. Calidad
R1.4. Política de uso de librerías, herramientas y contenidos de terceros R1.12. Accesibilidad
R1.5. Analítica, crashes y notificaciones push R1.13. Política de integración con redes sociales
R1.6. Requisitos funcionales R1.14. Integración cartografía municipal
R1.7. Módulos de la OSAM R1.15. Documentación
R1.8. Gestión multiidioma  

 

R1.1. Gestión del código fuente, distribución y publicación

  • R1.1.1. Las aplicaciones publicadas por el Ayuntamiento son propiedad de este y, por tanto, habrá que proporcionar el código fuente de estas y todo el material necesario para su distribución, publicación y mantenimiento.
  • R1.1.2. Por defecto, cualquier recurso que necesiten las apps (archivos de configuración, archivos, imágenes, servidor de aplicaciones / web, ...), deberán estar instalados en los servidores del IMI y gestionado por la OSAM. En caso de que no sea posible se comunicará a la OSAM para tomar una decisión.
    • En la fase de diseño y prototipaje de la aplicación, los diseños deberán ser entregados con una herramienta que permita el acceso, ya sea de licencia libre o con una licencia o acceso que facilite el proveedor, y en un formato que permita obtener, de forma inequívoca, los códigos de color de cada elemento.
    • En el caso de que el diseño incluya componentes (botones, selectores, menús, carruseles, etc.) con unas funcionalidades hechas a medida (es decir, que no estén basadas en elementos nativos) se deberá especificar en la propia herramienta de diseño o en un documento aparte como será exactamente esta funcionalidad y qué modificaciones se prevén hacer.
  • R1.1.3. Las nuevas aplicaciones que se creen se recomienda que puedan ser publicadas bajo una licencia OpenSource por parte del Ayuntamiento. En caso de que sea así, antes de comenzar el proyecto, es necesario que el equipo de desarrollo se ponga en contacto con la OSAM para acordar el tipo de licencia.
  • R1.1.4. Desarrollo. Para nuevos desarrollos deberá usarse Flutter, ya que es el framework que la OSAM recomienda utilizar para nuevos desarrollos, al ser la tecnología escogida por el Ayuntamiento como herramienta de desarrollo por ser la que mejor se adapta a sus necesidades: calidad, complejidad, velocidad y coste de desarrollo. Se pueden consultar los requisitos específicos de Flutter en: R4. Requisitos específicos Flutter
    • En caso de que se quiera utilizar otro framework será necesario que se justifique previamente y sea aprobado por parte de la OSAM.
    • Por este motivo, la OSAM proporciona plugins en Flutter para poder usar las librerías y módulos que desarrolla. Si se usa otro framework, es responsabilidad del proveedor generar los plugins necesarios para poder usar estas librerías y módulos comunes.
    • R1.1.4.1. Durante el proceso de desarrollo, el proveedor deberá utilizar sus credenciales, claves y recursos propios, como son, por ejemplo: Bundle ID para IOS, package para Android, Keys de Firebase, keys de Analytics, key de Google Maps, etc. Estos recursos son diferentes a los de Producción, que serán informados durante el proceso de publicación por parte de la OSAM.
  • R1.1.5. Distribución. Para facilitar la distribución de las aplicaciones para su test durante el periodo de desarrollo, se pide el uso de una plataforma que permita la distribución sin necesidad de uso de iTunes ni consultar el UDID del dispositivo por parte de la persona usuària.
    • Como ejemplo de sistema con estas características se puede utilizar utilitzar Firebase App Distribution, en la consola de Firebase (https://console.firebase.google.com/).
    • Esta distribución la gestionará el proveedor.
    • En el caso de las aplicaciones que tengan necesidades especiales, se deberá consultar con la OSAM al respecto.
      • Tanto para la distribución interna dentro de la OSAM como con los proveedores y clientes, la herramienta oficial será Firebase App Distribution.
  • R1.1.6. Publicación.
    • R1.1.6.1. Para la publicación de las aplicaciones son necesarios los siguientes recursos gráficos:
      • Todas las aplicaciones:
        • Icono de la aplicación: Sus dimensiones son: 512x512
      • Android:
        • Capturas de pantalla: Deben ser en formato .png o .jpg. Su nomenclatura debe tener el nombre, idioma y el número de la imagen siguiendo el siguiente formato: nombreImagen_AA_00.extensión (ej: nombre_ref_es_01.png, nombreref_ca_01.jpg). Deben incluirse como mínimo 4 y un máximo de 8 imágenes para cada idioma de la app, con una resolución mínima de 1080 px. La relación de aspecto debe ser de 16:9 para las capturas de pantalla horizontales (1920x1080 px) y de 9:16 para capturas de pantalla verticales (1080x1920 px).
        • Feature Graphic: Imagen de cabecera. Sus dimensiones son 1024x500 px.
      • iOS:
        • Capturas de pantalla: Deben ser en formato .png o .jpg. Su nomenclatura debe tener el nombre, idioma y número de la imagen siguiendo el siguiente formato: nombreImagen_AA_00.extensión (ej: nombreref_es_01.png, nombreref_ca_01.jpg). Para iOS es necesario incluir como obligatorias las capturas de pantalla de iPhone Plus, iPhone XS Max e iPad Pro (un mínimo de 1 y un máximo de 10 capturas de pantalla por dispositivo), repitiendo esto por cada idioma de la app (es decir, para una app en catalán y castellano, se incluirán como mínimo 6 imágenes). Sus dimensiones son las siguientes:
          • iPhone con pantalla de 5,5": Altura 2208px, anchura1242 px
          • iPhone con pantalla de 6,5": Altura 2688 px, anchura 1242 px
          • iPad con pantalla de 12,9": Altura 2732 px, anchura 2048 px
  • R1.1.6.2. Para agilizar la compilación, todas las apps y actualizaciones tienen que ser compatibles con la integración continua del Ayuntamiento para iOS y Android. En el documento Manual Integración Continua para Proveedores se indican los pasos a seguir, tanto para configurar el proyecto, como para subir el código al repositorio Gitlab del Ajuntament.
  • R1.1.6.3.
    • Las aplicaciones para móviles del Ayuntamiento se publicarán en las cuentas que este tiene en los diferentes Markets y que gestiona la OSAM. Por tanto, todas las claves, certificados y otros que se requieran para la publicación serán gestionadas a través de esta cuenta. En ningún caso se proporcionarán claves, certificados, usuarios y otra información privada al desarrollador.
    • Para las versiones de producción se utilizarán las credenciales, claves y recursos propios de OSAM. En concreto: Bundle ID para IOS, package para Android, Keys de Crashlytics, keys de Analytics, key de Google Maps y archivo de parametrización del control de versiones. Estos códigos no se facilitarán al proveedor y se introducirán al código fuente por parte de los técnicos de OSAM durante el proceso de compilación.
      • Es importante que el proveedor no utilice ni el Bundle ID ni el package para Android en su cuenta de los markets.
  • ​​R1.1.6.4. Para poder preparar correctamente la publicación de la app, la persona responsable deberá informar al jefe de proyecto de la OSAM previamente al envío a Palantir si la publicación de una nueva versión será full roll-out (si se publicará inicialmente al 100% de las personas usuarias) o será progresiva (si se publica inicialmente a un número pequeño de personas usuarias y progresivamente va aumentando este número).

R1.2. Diseño visual

  • R1.2.1. Las apps desarrolladas para el Ayuntamiento de Barcelona deben seguir la guía de estilo definida a tal efecto. Podremos definir tres tipos de apps, las estándar, las específicas y las de productos. Cada una de ellas dispondrá de su propia guía de estilo, las cuáles se podrán consultar en las siguientes webs:
  • R1.2.2. Además de la guía de estilo, las aplicaciones deberán seguir los siguientes requisitos visuales:
    • Las aplicaciones que dispongan de la funcionalidad de agregar a favoritos, el icono debe ser preferiblemente una estrella para unificar a nivel de todas las apps municipales. Si hace falta otro uso habrá que consensuarlo con la OSAM.
    • Para evitar problemas de seguridad en los campos de texto donde se tengan que introducir contraseña, hay que definir correctamente las áreas como "textPassword" para Android y "texfield.secureTextEntry = true" para IOS.

R1.3 Privacidad y protección de datos

  • R1.3.1. RGPD. Las apps del Ayuntamiento de Barcelona deben cumplir con la normativa vigente sobre protección de datos y privacidad de datos. En concreto, deberán tener en cuenta a nivel europeo el Reglamento General de Protección de Datos (2016/679) y a nivel estatal la Ley Orgánica de Protección de Datos y Garantía de Derechos Digitales (LO 3/2018, de 5 de diciembre).
  • Dado que la afectación de estas normativas va más allá del propio funcionamiento de las apps, la responsabilidad sobre la correcta aplicación de estas es del responsable o promotor de la aplicación. A pesar de ello, y sin ánimo de menoscabar la total aplicación de estas normativas, a continuación nombramos algunos de los requisitos que habrá que tener en cuenta a relación a estas y que serán validados por la OSAM:
    • Cuando se guarden, usen o muevan datos personales, se debe solicitar y recibir el consentimiento explícito e inequívoco del usuario para poder proceder. Al iniciarse la app se mostrará una pantalla en la que se solicitará este consentimiento al usuario mediante una serie de mensajes que solicitan permisos al usuario y que este deberá aceptar. Si no se aceptan estas condiciones de servicio, la app se detendrá, por lo que se ha de validar que estos permisos estén informados.
    • Para todas las apps que tengan condiciones de aceptación de servicio, hay que prevenir que estas condiciones pueden cambiar. Por tanto, hay que tener un mecanismo que permita forzar a aceptar estas condiciones cuando cambien, volviendo a mostrar la pantalla en que se solicita el consentimiento al usuario mostrando las nuevas condiciones.
    • Una vez el usuario ha aceptado las condiciones del servicio, la pantalla en la que se solicita su consentimiento no volverá a aparecer, a menos que las condiciones de aceptación cambien.
    • La información personal de los usuarios se encriptará con algoritmos robustos para minimizar la afectación de brechas en la seguridad. Por el mismo motivo, las comunicaciones con servidores deberán realizarse bajo el protocolo HTTPS.
  • R1.3.2. Gestión de permisos. Hay que tener en cuenta que las aplicaciones, y sus actualizaciones, deben implementar la gestión de permisos "on demand", es decir, se pedirán a medida que lo necesite la app no al inicio o en un momento que por el contexto el usuario no pueda entender para qué necesita conceder este permiso. También se dará la explicación de por qué es necesario este permiso justo antes o en el mismo momento de pedirlo.
    • Para gestionar correctamente las notificaciones push en dispositivos Android 13 o superiores, las aplicaciones deben tener como targetSDK 33 o superior, y se deberá añadir el permiso POST_NOTIFICATIONS al AndroidManifest. Una vez abierta la app, y en el momento que se considere adecuado según las especificaciones de cada app, se deberá mostrar un pop-up o pantalla indicando si quiere recibir las notificaciones push y por qué recibirá notificaciones. Si Acepta, solicitaremos el permiso de push, para que el usuario acepte recibir notificaciones. Si Cancela, las notificaciones quedarán bloqueadas y la app no las recibirá.
    • Si un permiso es imprescindible para el funcionamiento de la app, se deberá dejar claro que es así al usuario cuando se le pida, y si el usuario no da el permiso se deberá mostrar un mensaje informativo, explicando que como no se ha concedido el permiso no se puede seguir con el funcionamiento de la app, y cerrar la app. No se puede producir un crash ni volver a pedir los permisos hasta que se vuelva a iniciar la app.
    • Si la persona usuaria no da un permiso necesario para el funcionamiento de la app, se deberá mostrar un mensaje informativo y cerrar la app. No se puede producir un crash ni volver a pedir el permiso hasta que se vuelva a iniciar la app.
    • Si la persona usuaria deniega la concesión de un permiso, pero vuelve a acceder a una funcionalidad o pantalla en la cual la app le pediría este permiso, se mostrará un pequeño mensaje en una zona visible de la pantalla recordando al usuario que ha denegado el permiso de la aplicación y con un botón de "Configuración" que al clicarlo lleve a la configuración de la app por si quiere cambiarlo y dar el permiso. El texto del mensaje se mostrará en el idioma de la app.

missatge de permís denegat

R1.4. Política de uso de librerías, herramientas y contenidos de terceros

  • R1.4.1. A pesar de esto, a continuación enumeramos algunos de los requisitos que habrá que tener en cuenta cuando se utilicen librerías y/o contenido de terceros:
    • En caso de utilizar mapas de Google o Apple hay que garantizar la normativa de uso vigente para cada una de las plataformas, utilizando siempre la última versión disponible del sistema.
    • En caso de ser necesario utilizar una API Key de Google, esta no debe ponerse hardcoded, sino que se debe esconder la key en variables de entorno o codificarla para que no pueda ser visible en el código fuente. Si la API Key se guarda en archivos, que estos estén fuera del árbol de código de la aplicación.
    • Si se utiliza alguna librería que requiera pago y/o tener tarjeta de crédito, se deberá consultar con la OSAM previamente al desarrollo.
    • La aplicación no puede contener materiales con derechos de autor propiedad de terceros (incluyendo música, fotos, vídeo, esculturas, pinturas y otras obras de arte o imágenes publicadas en sitios web o en la televisión, películas u otros medios) sin la correspondiente cesión de los derechos de explotación de forma expresa y por escrito.
    • Si la aplicación requiere por parte del desarrollador de una cuenta en un tercer sistema (redes sociales, Google Maps, notificaciones push, videoconferencia, etc.) OSAM será quien proporcionará las claves para este. Nunca se utilizará una cuenta propia del desarrollador o del cliente.
  • R1.4.2. En caso de usar cualquier framework multiplataforma como Flutter, IONIC, React Native o Xamarin, entre otros, al inicio del proyecto deberán usarse las últimas versiones estables de los mismos. Cuando se entregue el código deberá usarse como mínimo la penúltima versión estable de los frameworks.
  • R1.4.3. A continuación enumeramos los requisitos relativos a las llamadas a servicios por parte de las apps, ya sean servicios de terceros o servicios propios ubicados en un backend propio:
    • Recomendamos que las apps tengan un sistema para deshabilitar las llamadas a servicios de terceros, de manera que si se detecta un error o se despublica la app se garantiza que no se realizan estas llamadas. Este sistema puede ser, por ejemplo, unas variables en el Remote Config de Firebase que permitan deshabilitar estas llamadas.
    • Las apps deberán tener un sistema para deshabilitar el acceso a los servicios ubicados en un backend propio. Por ejemplo, mediante la propia configuración del backend.

 

R1.5. Analítica, crashes y notificaciones push

Firebase es una plataforma para el desarrollo de aplicaciones móviles que permite tener analítica y gestionar los crashes y las notificacions push.

  • R1.5.1. Integración con Firebase Analytics. Todas las apps publicadas deberán integrar como herramienta de analítica a Firebase Analytics:
    • Composición y configuración de las herramientas:
      • Todas las apps publicadas deberán integrar Firebase Analytics, utilizando la última versión estable del SDK de Firebase disponible en el momento de su incorporación al proyecto.
      • Como en cualquier otra herramienta de terceros, por las versiones de producción se utilizarán los códigos generados a partir de las cuentas de OSAM. OSAM facilitará el acceso de lectura a Firebase tanto al cliente como al proveedor, si así lo requieren.
    • Registro de datos:
      • La aplicación debe registrar como mínimo en el Screen Name de Firebase Analytics el nombre de las pantallas visualizadas en la aplicación, además de dejar que el Screen class se informe automáticamente. Los nombres de las pantallas deberán ser claros y autoexplicativos, de modo que sólo por el nombre ya se pueda saber a qué pantalla hace referencia. Estos nombres serán iguales para todas las plataformas (Android e iOS).
      • También se debe registrar el evento de cambio de idioma, identificado mediante una variable con el nombre 'language_change'. Este evento se registrará la primera vez que se inicie la app y también con cada cambio de idioma. Esta variable tendrá tres parámetros:
        • "previous_language": que informará del idioma de la app previo a realizar el cambio de idioma. Si se está registrando el evento la primera vez que se inicia la app, este parámetro estará vacío.
        • "selected_language": que informará del idioma de la app al iniciar la app y una vez se realice el cambio de idioma.
        • "language_disp" que registrará el idioma actual del dispositivo al iniciar la app.
      • Donde el idioma se informará mediante un label con un código de dos letras, según el idioma ISO correspondiente (ex.CA, ES, EN, FR,...).
    • Durante la fase de desarrollo:
      • El proveedor deberá utilizar sus propios códigos para validar que el sistema de analítica funciona correctamente.
      • Los proveedores deberán proporcionar acceso a OSAM para consultar las estadísticas de desarrollo para su validación previa.
  • R1.5.2. Integración conFirebase Crashlytics. Para poder gestionar los crashes de las aplicaciones e informar al proveedor de los mismos, se debe incorporar a todas las aplicaciones la herramienta de gestión de crashes, Firebase Crashlytics.
    • OSAM proporcionará la documentación necesaria para la integración y utilización de esta herramienta, además de dar la API KEY para incorporar al proyecto. En la documentación oficial de Google, podemos ver cómo realizar esta integración.
    • Como en todas las herramientas de terceros utilizadas en OSAM, durante el desarrollo el proveedor utilizará crashlytics con su propia cuenta y keys generadas por él. Si OSAM lo requiere habrá que darle acceso de lectura.
    • Crashlytics tiene que estar inicializado en la clase Application (Android).
    • Cuando la app haga una llamada a una API y se produzca un error controlado, se deberá hacer una llamada a Crashlytics para registrar el error como Non-Fatal (o error recuperable) y los datos que sean importantes para diagnosticar el error: traza con la llamada que se ha realizado, código de error que permita identificar rápidamente el tipo de error, y el texto con el error devuelto por el servidor. En este enlace se accede a la documentación oficial de Firebase para registrar este tipo de errores en Flutter.
  • R1.5.3. Notificaciones push. Las notificaciones push serán obligatorias para todas las nuevas apps o actualizaciones de apps existentes, utilizando la plataforma Firebase Cloud Messaging. Este requisito es independiente de que la app tenga otro sistema de notificaciones push.
    • Se recomienda a los proveedores usar la llave de autenticación de APNS, en la fase de desarrollo de sus apps iOS, para validar el funcionamiento de las notificaciones push por medio de la consola de Firebase. Firebase recomienda esta configuración y es la que por defecto usará la OSAM en las aplicaciones de producción.
    • La notificación se mostrará según la opción por defecto del sistema operativo y la configuración de visualización elegida, no será necesario hacer ninguna adaptación adicional.
    • Requisitos:
      • Con la app en foreground se notificarán a la persona usuaria mediante un pop-up:

notificació pop-up

  • Con la app en background se notificarán en la barra de herramientas mediante un icono:

notificació es mostra en el toolbar

  • El icono de la notificación deberá ser representativo de la app, recomendable que se parezca al icono de launcher.
  • Cualquier otra customización se deberá consensuar previamente con la OSAM.
  • Si la aplicación tiene una opción de menú para consultar las notificaciones, estas quedarán registradas cuando se generen (si la app está instalada) y las más recientes se podrán consultar con esta opción de menú. Si todavía no han sido consultadas, se mostrará un superíndice con un número encima del icono de la app en el escritorio del dispositivo (si está configurado para que se muestre el número). El número tendrá el número de notificaciones pendientes de consultar.

mostra número

 

  • Topics:
    • Habrá que implementar un topic para poder enviar una notificación push para una versión determinada de la app. Este topic seguirá la siguiente nomenclatura: nomApp_X.Y.Z_buildNumber para iOS y nomApp_X.Y.Z_versionCode para Android, y se realizará la subscripción al abrir la app.
    • Deberá utilizarse como mínimo un topic para cada idioma que tenga la aplicación, identificados mediante un label con un código de dos letras, según el idioma ISO correspondiente (ej: CA, ES, EN, FR, ...). En relación con estos topics, la aplicación tendrá que estar suscrita únicamente al topic referente a su idioma actual, y en el caso de que el usuario cambie el idioma de la aplicación se deberá anular esta subscripción y realizar una nueva al topic referente al nuevo idioma.
  • Deben ser visibles con pantalla emergente, no sólo con un aviso de tipo "campanilla".
  • Si son necesarias funcionalidades adicionales que no proporciona Firebase se deberá consultar con la OSAM para decidir la mejor solución.
  • La gestión de las notificaciones será delegada al cliente, pero será la propia OSAM quien de permisos para poder realizar esta gestión.

Para ayudar a solucionar los problemas que puedan aparecer con la integración con Firebase, la OSAM ha preparado este documento, en el cual se describen problemas que se han detectado y su solución.

R1.6. Requisitos funcionales

Además de los requisitos funcionales requeridos por negocio, todas las apps del Ayuntamiento de Barcelona tienen que seguir los siguientes puntos:

  • R1.6.1. El splash screen es necesario que se presente un mínimo de 2 segundos al iniciar la aplicación.
  • R1.6.2. La siguiente información debe ser de acceso fácil y directo (sin necesidad de hacer login en la aplicación u otra acción previa) en todas las aplicaciones.
    • Un apartado de ayuda para los usuarios. Como mínimo contendrá:
      • Descripción de la app, objetivos y apartados
      • Un método de contacto con el Ayuntamiento. Si la persona responsable de la app no proporciona uno mediante el sistema de gestión de incidéncias IRIS (Incidéncias, Reclamaciones y Sugerencias), se deberá indicar el correo electrónico mobil@bcn.cat. En el caso que se quiera otra opción, se comunicará a la OSAM para acordar la mejor solución.
        • Al clicar en el mail, se abrirá la aplicación de correo por defecto del móvil con el destinatario informado, y se deberá mostrar la siguiente información:
          • Asunto: "Contacto Nombre Aplicación". Este texto se mostrará en el idioma de la aplicación.
          • Cuerpo del mensaje: Información del dispositivo y de la app, con un texto informando al usuario que a continuación describa sus motivos para contactar. Este texto se mostrará en el idioma de la aplicación. Para obtener la información del dispositivo y de la app se debe tener instalado el módulo común de la OSAM, como se indica en este documento en el requisito R1.7.
    • Para aquellas apps en las cuales se haya realizado un informe de accesibilidad, se deberá incluir un enlace a la declaración de accesibilidad. Este enlace será proporcionado por la OSAM.
    • Autoría del proyecto. Por defecto es "Ayuntamiento de Barcelona".
    • Justificación del uso de datos. Se puede usar el siguiente texto como modelo:
      • "La aplicación XXXX se puede descargar gratuitamente. Su uso requiere de una conexión de datos activa, ya sea wifi o a través de la red de telefonía". Añadir "Se recomienda tener activado el GPS" para los casos en los que la app tenga geolocalización.
    • Número de versión de la aplicación y el versionCode / build versión dependiendo de la plataforma (cogiéndolo dinámicamente del binario).
    • Habrá que indicar si la versión de la aplicación está funcionando en un entorno de Pre-producción o Producción, donde el primero es un entorno de pruebas.
  • R1.6.3. Si la aplicación está abierta, al clicar de nuevo en el icono hay que abrirla en el punto que se encontraba, y no arrancar de nuevo.
  • R1.6.4. Si la aplicación requiere descargar un volumen de datos superior a 20mb, se informará previamente al usuario con un mensaje advirtiendo de la situación, dando la posibilidad de no hacerlo (explicando las consecuencias) y recomendando el uso de wifi. Si es posible para el buen funcionamiento de la aplicación, esta descarga de información se haría en segundo plano.
  • R1.6.5. En el caso de que una URL se quiera mostrar dentro de la app con un webview interno, la página correspondiente deberá estar optimizada para ser mostrada de tal forma, y por lo tanto, integrada con el diseño y funcionalidad de la app. Cualquier enlace que haya dentro de esta página, deberá cumplir el mismo requerimiento. Si se quiere enlazar a una página que no cumpla este requerimiento, será necesario abrirla en el navegador por defecto del sistema operativo.
  • R1.6.6. Si una funcionalidad de la aplicación implica como llegar a un destino, y ésta lleva a fuera de la app, debe indicarse al usuario la posibilidad de seleccionar entre las diferentes aplicaciones de navegación que tiene instaladas en su dispositivo, delegando en el sistema operativo esta selección.

R1.7. Módulos de la OSAM

Desde la OSAM se proporcionan módulos de uso obligatorio para realizar un conjunto de tareas comunes a todas las apps publicadas por el Ayuntamiento de Barcelona. Estos módulos son descargables desde https://ajuntamentdebarcelona.github.io/ o https://github.com/AjuntamentdeBarcelona , siendo obligatorio descargar siempre la última versión publicada.

Todas las apps del Ayuntamiento deben incorporar el Módulo común (R1.7.1).

  • 1.7.1. Módulo común. Este módulo integra las siguientes funcionalidades: control de versiones, control de valoraciones y obtención de información del dispositivo y aplicación.
    • Control de versiones: muestra, según el tipo de restricción, un popup que informa e invita al usuario a actualizarse la app en el market correspondiente (GooglePlay o AppStore). El objetivo es que no se pueda usar la app en caso de estar activado.
    • Control de valoraciones: muestra, a partir de una periodicidad y un número de ejecuciones, un popup que invita al usuario a valorar la aplicación en el market correspondiente (GooglePlay o AppStore).
    • Obtención de información del dispositivo y aplicación: devuelve información del dispositivo, como modelo, versión de OS, versión de la aplicación, etc.
  • El control de versiones debe mostrar siempre en las apps de forma individual antes de iniciar la Splash Screen y cada vez que pase del estado de inactividad a actividad (background -> foreground), teniendo en cuenta que no se han de hacer otras llamadas o peticiones antes de llamar a este módulo.
  • El comportamiento del módulo común se hace en tiempo real por la OSAM en producción. En la fase de desarrollo, el proveedor podrá usar una URL de desarrollo proporcionada por el Ayuntamiento.

Se puede descargar el módulo común desde Github.
Se puede consultar el manual del módulo en el archivo README al Github.

La OSAM proporcionará un manual donde se explica como, en un entorno de Desarrollo, poder validar que el módulo común se ha implementado correctamente.

Flutter

Para el framework Flutter, la OSAM dispone de un plugin que implementa la funcionalidad de la librería nativa.

Se puede descargar el plugin del módulo común desde Github.
Se puede consultar el manual del plugin en el archivo README al Github.

Integrar el módulo común en aplicaciones de frameworks diferentes a Flutter

Es responsabilidad del proveedor integrar el módulo común con otros frameworks diferentes a Flutter. En el supuesto que no sea posible esta integración, y previamente con la autorización de la OSAM, el proveedor deberá implementar uno de propio con las funcionalidades del módulo común, que deberá lanzar eventos de Firebase que registren cuando se llama al módulo. Deberá comunicarlo al JdP OSAM, explicando detalladamente su funcionamiento y su implementación, y en el test de pruebas que se entrega en la publicación de la app deberá explicar cómo probar el correcto funcionamiento del módulo.

R1.8. Gestión multidioma

  • R1.8.1. Las aplicaciones, como mínimo, deben estar en catalán y castellano, y es recomendable que también estén en inglés. Los idiomas disponibles deben coincidir con los especificados en el código fuente / binario y, por lo tanto, con los que especificarán los correspondientes markets.
  • R1.8.2. Tienen que habilitar una función dentro de la aplicación, previamente al login o registro de la app, que permita cambiar entre los diferentes idiomas. El cambio será automático y no puede suponer un reinicio de la aplicación.
  • R1.8.3. Inicialmente, las aplicaciones tienen que usar el idioma por defecto del dispositivo. En caso de no coincidir con ninguno de los idiomas disponibles, la aplicación se ejecutará en inglés si este idioma está disponible en la app o en catalán si no es así, con la posibilidad de cambiarlo manualmente.

R1.9. Versionado

  • El número de versión debe seguir la siguiente nomenclatura:
    • X – Versión mayor utilizada para cambios funcionales importantes
    • Y – Versión menor utilizada para cambios funcionales pequeños o actualizaciones de datos
    • Z - Este número sólo cambiará si hay varias iteraciones con la OSAM en el proceso de publicación, o si se publica una versión urgente para solucionar un error grave.
  • Para aplicaciones nuevas, la primera versión que se publica debe ser 1.0.Z, donde Z dependerá del número de iteraciones que se hayan realizado una vez la versión se ha entregado a la OSAM. Por ejemplo, si la versión entregada se ha publicado en Producción directamente sin detectarse ningún problema, sería 1.0.0. Si han debido realizar dos versiones correctivas adicionales, entonces será 1.0.2.

R1.10. Rendimiento

  • R1.10.1. Se debe integrar el sdk de Firebase Performance (https://firebase.google.com/docs/perf-mon) en las aplicaciones del Ayuntamiento, para poder hacer una monitorización de su rendimiento. Se recomienda que se monitoricen todas las llamadas que se hagan desde la app.
  • R1.10.2. Toda funcionalidad del sistema y transacción de negocio tiene que responder al usuario en menos de 5 segundos en un 90% de las peticiones. Se debe tener en cuenta també la siguiente información:
    • 0.1 segundos es el límite para que el usuario sienta que el sistema reacciona instantáneamente, es decir, que no necesita ninguna retroalimentación especial, excepto para mostrar el resultado.
    • En las consultas cuyo tiempo sea superior a 1 segundo, se deberá mantener la atención del usuario ocupada con un spinner, barra de progreso, etc; un elemento que muestre que la app está funcionando y no se ha quedado bloqueada.
    • 10 segundos es el límite para mantener la atención del usuario centrada en la ap. En caso de superarse este tiempo, se deberá producir un time out, cancelar la petición e informar al usuario.
  • El proceso de arrancar (startup) no deberá superar los tiempos indicados en un 95% de las ocasiones:
    • La cold startup tarda 5 segundos o más.
    • La warm startup tarda 2 segundos o más.
    • La hot startup tarda 1.5 segundos o más.

Se puede consultar la definición de estos términos en Android Vitals

R1.11. Calidad

  • R1.11.1. Todas las Apps tendrán que venir acompañadas del plan de pruebas correspondiente para que OSAM, durante el proceso de testing interno del ciclo de vida, pueda validar el correcto funcionamiento de la aplicación y evidenciar que se ha hecho un juego de pruebas válido.
    • El proveedor tendrá que entregar el resultado de este plan de pruebas realizado en cada versión, con el objetivo de validar la corrección de la versión.
  • R1.11.2. La OSAM ha definido unos criterios de calidad para las apps. Estos criterios se han definido con la herramienta SonarQube (https://www.sonarsource.com/products/sonarqube/), que usa la OSAM en el proceso de publicación, y son los siguientes:
    • Para el código nuevo de la versión:
      • Las líneas duplicadas no pueden superar el 1% del código
      • Mantenimiento del código debe ser mejor que una B
      • Fiabilidad del código debe ser una A
      • No pueden haber security hotspots sin revisar
      • La seguridad debe ser una A. No pueden haber bugs ni vulnerabilidades
    • Para el código general de la app:
      • Las líneas duplicadas no pueden superar el 3% del código
      • Mantenimiento del código debe ser mejor que una C
      • Fiabilidad del código ha de ser una A
      • No pueden haber security hotspots sin revisar
      • La seguridad debe ser una A. No pueden haber bugs ni vulnerabilidades
  • Durante el proceso de publicación de una app se enviará un mail con el análisis del código. Si se quiere ver con más detalle los resultados del análisis de las aplicaciones se puede acceder al SonarQube de la OSAM. Si no tenéis acceso, podéis pedirlo enviando un mail a la OSAM.
  • Es obligatorio cumplir con estos criterios de calidad del código, y las apps que incumplan alguno de los criterios mencionados no se publicarán.

R1.12. Accesibilidad

El Real Decreto 1112/2018, sobre accesibilidad de los sitios web y aplicaciones para dispositivos móviles del sector público y que es de obligatorio seguimiento para todos los organismos públicos, establece los condicionantes, con respecto a la accesibilidad, que deberán cumplir todas las webs y aplicaciones móviles del sector público. En este sentido, las aplicaciones deberán ser accesibles siguiendo los criterios de la guía de accesibilidad en aplicaciones nativas para dispositivos móviles, actualizada recientemente con los requisitos WCAG 2.1.

Para facilitar la validación de la accesibilidad de una aplicación se recomienda la utilización de las siguientes herramientas de Google, según la plataforma:

R1.13. Política de integración con redes sociales

Si compartimos un enlace o una imagen en una red social, este no tendría que ser genérico de una web, sino que apunte directamente a la información que se quiere compartir. Por ejemplo, si estamos en una aplicación que muestra un conjunto de actividades y queremos compartir una de ellas, el enlace tendría que llevar a la actividad concreta y no a una web genérica de la app.

R1.14. Integración cartografía municipal

  • R1.14.1. Toda app nueva y todas las actualizaciones de las apps del Ayuntamiento han de integrar la cartografía municipal, en aquellas apps con ámbito territorial exclusivo en Barcelona. Se deben tener en cuenta los siguientes puntos:
    • Se recomienda el uso del framework de mapas Mapbox.
    • Las apps del Ayuntamiento desarrolladas en Flutter pueden usar el siguiente plugin para integrar Mapbox: https://pub.dev/packages/mapbox_maps_flutter. En la web de Mapbox se puede encontrar la documentación oficial para integrarlo tanto para Android como para iOS.
  • R1.14.2. Cartografía municipal: Para poder integrar la cartografía municipal del Ayuntamiento, la OSAM pone a disposición para el desarrollo la siguiente url: https://cdn-geo.bcn.cat/XYZ/PLANOLBCN_WEB/ . La cartografía en este enlace será la misma para todas las apps del Ayuntamiento y es de uso obligatorio.

R1.15. Documentación

Es necesario que el proyecto tenga un mínimo de documentación:

  • R1.15.1. README: En el readme del proyecto debe estar detallada la siguiente información:
    1. Requisitos para poder ejecutar la aplicación. Estos serán la versión usada para construir la aplicación (Android SDK, iOS, Flutter), configuración de Mapbox y otros requisitos si fuese necesario.
    2. Pasos para ejecutar y construir el proyecto
    3. Descripción de los entornos
  • R1.15.2. Notas de lanzamiento: El archivo release_notes.txt debe estar en al carpeta raíz del proyecto. Deberá contener todos los cambios des del lanzamiento de la última compilación y distribución. El formato puede ser como una lista en la cual cada punto tiene la descripción de la funcionalidad.
  • R1.15.3. Changelog: En las apps nuevas, el archivo changelog.md debe estar en la carpeta raíz del proyecto. Deberá contener todos los cambios realizados durante el proyecto, separandolos por cada versión que se haya distribuido. Para poder automatizar la generación de este archivo se recomienda usar conventional commits (https://www.conventionalcommits.org/).