Repository files navigation

• FAQ
  • What is the Digital Citizenship project?
  • What is the Digital Citizenship mobile app?
  • Who develops the app?
  • Can I use the app?
  • How can I help you?
  • What permissions are used by the IO app?
• Getting started
  • Prerequisites
  • Build the app
  • Environment variables
  • Run the app
  • Troubleshooting
• Architecture
  • Main technologies used
  • SPID Authentication
  • Deep linking
  • Design System
• Appendix
  • Internationalization
  • End to end test

Digital Citizenship aims at bringing citizens to the center of the Italian public administrations services.

The project comprises two main components:

• a platform made of elements that enable the development of citizen-centric digital services;
• an interface for citizens to manage their data and their digital citizen profiles.

The Digital Citizenship mobile app is a native mobile application for iOS and Android with a dual purpose:

• to be an interface for citizens to manage their data and their digital citizen profile;
• to act asreference implementation of the integrations with the Digital Citizenship platform.

The development of the app is carried out by several contributors:

• PagoPA S.p.A.;
• volunteers who support the project.

Sure! However you will need aSPID account or have aCIE to login to the app.

Reporting bugs, bug fixes,translations and generally any improvement is welcome!Send us a Pull Request!

Because different platforms have different types of Permissions below we have two sections about permissions requested by the IO app for both environments (iOS and Android). Some permissions may be defined but not used. Their presence is due to dependencies with third-party modules or because they are required by the target store.

The following sections provide instructions to build and run the app for development purposes.

To run the project you need to install the correct version of NodeJS and Ruby.We recommend the use of a virtual environment of your choice. For ease of use, this guide adoptsnodenv for NodeJS,rbenv for Ruby.

The node version used in this project is stored in.node-version,while the version of Ruby is stored in.ruby-version.

Follow theofficial tutorial for installing theReact Native CLI for your operating system.

If you have a macOS system, you can follow both the tutorial for iOS and for Android. If you have a Linux or Windows system, you need only to install the development environment for Android.

In order to build the app, we useyarn for managing javascript dependencies.As statedpreviously, we also usenodenv andrbenv for managing the environment:

# Clone the repository$ git clone https://github.com/pagopa/io-app# CD into the repository$cd io-app# Install NodeJS with nodenv, the returned version should match the one in the .node-version file$ nodenv install&& nodenv version# Install Ruby with rbenv, the returned version should match the one in the .ruby-version file$ rbenv install&& rbenv version# Install yarn and rehash to install shims$ npm install -g yarn&& nodenv rehash# Install bundle$ gem install bundle# Install the required Gems from the Gemfile# Run this only during the first setup and when Gems dependencies change$ bundle install# Install dependencies# Run this only during the first setup and when JS dependencies change$ yarn&& yarn setup# Install podfiles when targeting iOS (ignore this step for Android)# Run this only during the first setup and when Pods dependencies change$cd iOS&& bundleexec pod install&&cd ..# Generate the definitions from the OpenAPI specs and from the YAML translations# Run this only during the first setup and when specs/translations change$ yarn generate

You can target the production server by copying the included.env.production file to.env:

$ cp .env.production .env

You can also target theio-dev-api-server for development purposes by copying the included.env.local file to.env:

$ cp .env.local .env

An Android Emulator must becreated and launched manually.

An additional step is necessary because the Android emulator doesn't support the hardware-backed keystore. We've included a script in ourpackage.json to comment out this check:

# Disable hardware-backed keystore check before running the emulatoryarn lollipop_checks:comment

# Re-enable hardware-backed keystore check before committingyarn lollipop_checks:uncomment

Then, from your command line, run these commands:

# Perform the port forwarding$ adb reverse tcp:8081 tcp:8081;adb reverse tcp:3000 tcp:3000;adb reverse tcp:9090 tcp:9090# Run Android build$ yarn dev:run-android

# Run iOS build$ yarn run-ios

The React Native documentation provides auseful guide for running projects on physical devices.

This section lists possible solutions to problems you might encounter while building the app.

• TypeScript
• React Native
• Redux
• Redux Saga

The application relies on abackend for the authentication through SPID (the Public System for Digital Identity) and for interacting with the other components and APIs that are part of thedigital citizenship project.

The backend implements a SAML2 Service Provider that deals with user authentication with the SPID Identity Providers (IdP).

The authentication between the application and the backend takes place via a session token, generated by the backend at the time of the authentication with the SPID IdP.

Once the backend communicates the session token to the application, it is used for all subsequent calls that the application makes to the API exposed by the backend.

The authentication flow is as follows:

1. The user selects the IdP;
2. The app opens a webview on the SAML SP authentication endpoint implemented in the backend, which specifies: the entity ID of the IdP selected by the user and, as returns URL, the URL of the endpoint that generates a new session token.
3. The SAML SP logic takes over the authentication process by redirecting the user to the chosen IdP.
4. After the authentication, a redirect is made from the IdP to the backend endpoint that deals with the generation of a new session token.
5. The endpoint that generates a new token receives the SPID attributes via the HTTP header; then, it generates a new random session token and returns to the webview an HTTP redirect to an URL well-known containing the session token.
6. The app, which monitors the webview, intercepts this URL before the HTTP request is made, extracts the session token and ends the authentication flow by closing the webview.
7. Next, the session token is used by the app to make calls to the backend API.

The application is able to managedeep links.Deep linking allows opening the app or a specific screen once a user clicks on specific URL. The URL scheme for io-app is:ioit://.

The entire app is built using custom components included in the externalio-app-design-system library. This library uses the latest React Native APIs and is tailored to our specific needs.

We're committed to providing a faster and more satisfying experience for our citizens, but because we didn't build the app using fully native APIs, this goal is not easy to achieve. For iOS, we have already enabled the full range of refresh rates by settingCADisableMinimumFrameDurationOnPhone totrue, as recommended by Applein their documentation.

The perception of slowness is mainly due to the navigation architecture, which is actually handled by thereact-navigation library. Our internal testing has shown that there's a pretty obvious difference between the defaultStack navigation and theNativeStack, which uses native APIs underneath. The latter is currently only enabled in theDesign System section, which isn't accessible to everyone because it's only visible when developer mode is enabled.

We're actively developing a dark mode for the app that will be available in the coming months. The initial release will be a beta version to allow users to explore and provide feedback.

You can follow the related activities byfiltering the PRs with theDark Mode label

If you want to improve theio-app-design-system library, feel free to contribute by opening an issue with your suggestions or by directly opening a PR. Criticism is welcome and appreciated.