README.md

IO - The public services app

The mobile app of the Digital Citizenship project

• 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

FAQ

What is the Digital Citizenship project?

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.

What is the Digital Citizenship mobile app?

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 as reference implementation of the integrations with the Digital Citizenship platform.

Who develops the app?

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

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

Can I use the app?

Sure! However you will need a SPID account or have a CIE to login to the app.

How can I help you?

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

What permissions are used by the IO app?

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.

Android

Permission (android.permission.*)	Usage / Meaning
INTERNET	Allows the app to open network sockets (e.g. simple internet connectivity)
ACCESS_NETWORK_STATE	Allows the app to access information about networks (e.g. details about connection quality/state)
CAMERA	Allows the app to access device camera to scan QR codes
NFC	Allows the app to perform I/O operations over NFC
RECEIVE_BOOT_COMPLETED	Allows the app to receive the Intent.ACTION_BOOT_COMPLETED that is broadcast after the system finishes booting. Used for push notification.
VIBRATE	Allows the app to access the vibration motor. This allow the application to emit vibration.
WAKE_LOCK	Allows the app to use PowerManager WakeLocks to keep processor from sleeping or screen from dimming. Used for push notification.
READ_APP_BADGE	Allows the app to show notification badges on its icon.
READ_CALENDAR	Allows the app to read the user's calendar data.
WRITE_CALENDAR	Allows the app to write the user's calendar data. Used to automatically set reminders.
READ_EXTERNAL_STORAGE	Allows the app to read from external storage. Used to pick images from gallery with payment QRCode.
WRITE_EXTERNAL_STORAGE	Allows the app to write to external storage. Used to store images, certificates, etc.
USE_FINGERPRINT	Allows the app to use fingerprint hardware for biometric identification required from API level 23 until API level 28
USE_BIOMETRIC	Allows the app to use device's available biometric identification system (Face unlock, Iris unlock, Fingerprint) required from API Level 28.
SCHEDULE_EXACT_ALARM	Allows the app to send local notifications.
DOWNLOAD_WITHOUT_NOTIFICATION	Allows the app to download files in background without promping a notification.
POST_NOTIFICATIONS	Allows the app to post notifications. Used for push notification.

Below there are the permissions required by the main android hardware manufacturers. Mainly used to manage notification badge icons.

Permission (manufacturer)	Usage / Meaning
com.google.android.c2dm.permission.RECEIVE	Allows the app to receive a broadcast from a GCM server that contains a GCM message. Used for push notification.
com.google.android.finsky.permission.BIND_GET_INSTALL_REFERRER_SERVICE	Allows the app to recognize where the app was installed from. Used for Firebase.
com.anddoes.launcher.permission.UPDATE_COUNT	Allows the app to use notification badges.
com.htc.launcher.permission.READ_SETTINGS	Allows the app to use notification badges.
com.htc.launcher.permission.UPDATE_SHORTCUT	Allows the app to use notification badges.
com.huawei.android.launcher.permission.CHANGE_BADGE	Allows the app to use notification badges.
com.huawei.android.launcher.permission.READ_SETTINGS	Allows the app to use notification badges.
com.huawei.android.launcher.permission.WRITE_SETTINGS	Allows the app to use notification badges.
com.majeur.launcher.permission.UPDATE_BADGE	Allows the app to use notification badges.
com.oppo.launcher.permission.READ_SETTINGS	Allows the app to use notification badges.
com.oppo.launcher.permission.WRITE_SETTINGS	Allows the app to use notification badgee.
com.sec.android.provider.badge.permission.READ	Allows the app to use notification badges.
com.sec.android.provider.badge.permission.WRITE	Allows the app to use notification badges.
com.sonyericsson.home.permission.BROADCAST_BADGE	Allows the app to use notification badges.
com.sonymobile.home.permission.PROVIDER_INSERT_BADGE	Allows the app to use notification badges.
me.everything.badger.permission.BADGE_COUNT_READ	Allows the app to use notification badges.
me.everything.badger.permission.BADGE_COUNT_WRITE	Allows the app to use notification badges.
com.android.vending.CHECK_LICENSE	Allows the app to access Google Play Licensing.
com.samsung.android.providers.context.permission.WRITE_USE_APP_FEATURE_SURVEY	Allows the app to use the Samsung Developer SDK. Used for Samsung biometric identification.
com.fingerprints.service.ACCESS_FINGERPRINT_MANAGER	Allows the app to access the fingerprint hardware for biometric identification.

iOS

Permission	Usage / Meaning
NSAppleMusicUsageDescription	Allows the app to access the user’s media library.
NSBluetoothAlwaysUsageDescription	Allows the app to use the device’s Bluetooth interface.
NSBluetoothPeripheralUsageDescription	Allows the app to access Bluetooth peripherals and has a deployment target earlier than iOS 13.
NSContactsUsageDescription	Allows the app to access contacts to let you add them in calendar events.
NSLocationAlwaysUsageDescription	Allows the app to access the user’s location at all times and deploys to targets earlier than iOS 11.
NSLocationUsageDescription	Allows the app to access the user’s location information.
NSLocationWhenInUseUsageDescription	Allows the app to access the user’s location information while the app is in use.
NSMicrophoneUsageDescription	Allows the app to use the microphone in case you want to leave a voice note. Used in the assistance flow.
NSMotionUsageDescription	Allows the app to access the device’s motion data.
NSCalendarsUsageDescription	Allows the app to access the calendar to add event reminders.
NSCameraUsageDescription	Allows the app to use the camera to scan QR codes.
NSFaceIDUsageDescription	Allows the app to use Face ID for biometric identification.
NSPhotoLibraryAddUsageDescription	Allows the app to access the user’s photo library.
NSPhotoLibraryUsageDescription	Allows the app to access the photo library to scan QR codes.
NSSpeechRecognitionUsageDescription	Allows the app to send user data to Apple’s speech recognition servers. Used in the assistance flow.
Remote Notification	Allows the app to receive remote push notification.
NFC (Near Field Communication Tag Reading)	Allows the app to use the NFC.

Getting started

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

Prerequisites

NodeJS and Ruby

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 adopts nodenv 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.

React Native

Follow the official tutorial for installing the React 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.

Build the app

In order to build the app, we use yarn for managing javascript dependencies. As stated previously, we also use nodenv and rbenv 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 install

# Install podfiles when targeting iOS (ignore this step for Android)
# Run this only during the first setup and when Pods dependencies change
$ cd iOS && bundle exec 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

Environment variables

Production

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

$ cp .env.production .env

Note

The sample configuration sets the app to interface with our test environment, on which we work continuously; therefore, it may occur that some features are not always available or fully working. Check the comments in the file for more informations about environment variables.

io-dev-api-server

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

$ cp .env.local .env

Run the app

Android Emulator

An Android Emulator must be created 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 our package.json to comment out this check:

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

Caution

Always remember to run yarn lollipop_checks:uncomment or discard the changes before opening a PR. To automatically revert the changes, run the following command:

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

This is an important check that must be kept enabled. A double check is done by tests in the CI pipeline.

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

iOS Simulator

# Run iOS build
$ yarn run-ios

Physical devices

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

Important

For building the app on an iOS physical device, a few additional steps are necessary:

• Navigate to Build Phases in Xcode and expand Bundle React Native code and images. Update the NODE_BINARY variable with the path to your Node.js environment. You can find the correct path by running which node in a terminal from the app's root directory;
• If you're not part of the PagoPA S.p.A. organization then you must change the Bundle Identifier to something unique. This adjustment can be made in the Signing (Debug) section of Xcode;
• In order to test the CIE authentication flow, run yarn cie-ios:prod before building the app. The process can be reverted by running yarn cie-ios:dev.

Troubleshooting

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

iOS build

• error: redefinition of module 'YogaKit' build Failed
  

  Restart your machine to fix the issue.

  ---

• error No simulator available with name "iPhone 13".
  

  This happens because new versions of Xcode do not automatically create a simulator for the iPhone 13. To fix the issue you can either create a new simulator and name it iPhone 13 or run the command yarn run-ios --simulator='a valid simulator name'.

  ---

• Application launch for 'it.pagopa.app.io' did not return a valid pid nor a launch error. Domain: NSPOSIXErrorDomain Code: 3 Failure Reason: No such process User Info: { DVTErrorCreationDateKey = "2022-01-25 12:02:41 +0000"; IDERunOperationFailingWorker = IDELaunchiPhoneSimulatorLauncher; }
  

  This happens on Apple Silicon CPUs because some Pods do not implement the XCFramework yet. Install Rosetta by running softwareupdate --install-rosetta to fix the issue.

  ---

Architecture

Main technologies used

• TypeScript
• React Native
• Redux
• Redux Saga

SPID Authentication

The application relies on a backend for the authentication through SPID (the Public System for Digital Identity) and for interacting with the other components and APIs that are part of the digital 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.

Deep linking

The application is able to manage deep 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://.

Supported URLs

main

ioit://main/messages

ioit://main/services

ioit://main/profile

wallet

ioit://wallet

ioit://wallet/payments-history

ioit://wallet/card-onboarding-attempts

services

ioit://services/service-detail?serviceId=:id

profile

ioit://profile

ioit://profile/preferences

ioit://profile/privacy

ioit://profile/privacy-main

fci

ioit://fci/main?signatureRequestId=:id

ioit://fci/signature-requests

ioit://cgn-details/categories-merchant/:category

Design System

We have been gradually rolling out a new library of custom components since Q1 2023. This library uses the latest React Native APIs and replaces the legacy native-base library, which was stuck at v2.x.

You can access the new library through the external io-app-design-system package.