-
Notifications
You must be signed in to change notification settings - Fork 2
3. Services
A service represents a data layer that communicates with backend or system services and provides data in comfortable format for the UI. The services deal with data only and have no particular UI associated with this data.
The service is created and initialized on application startup and destroyed and dismissed on application shutdown. Often the services take care of keeping the internal data consistent and up to date during the lifecycle of a service. Often the services depend on each other so their initialization should be performed consequently and ordered by their dependency. The services are usually singleton factory instances.
Each service complies to the abstract Service interface. On application launch a service is first created (createService) and then initialized (initService). On shutdown it is destroyed (destroyService). There is a query for dependency of other services (serviceDependsOn) as well as a notification that all services are initialized and the application UI is ready to handle UI requests from services (initServiceUI).
Represents a set of services that build the application's data layer. The application creates the Services instance at app start time defining the list of services that should be maintained by Services instance. The services get sorted by their dependencies order. When a service initialization fails this could stop the entire services initialization process, in case the failure is fatal, or could be simply ignored otherwise. All other Services APIs broadcast a command or notification to this sorted list of services.
Analytics service logs user activity to the Splunk backend. Each log entry is arbitrary JSON content. The analytics log entries are first saved in a SQLite database and then uploaded to the Splunk backend. This ensures that there will be no logs loss when there is no internet connection or if an upload HTTP request fails by some reason.
AppDateTime service provides utilities related to date time processing. It contains tools for conversion between different time zones - university local time zone, UTC time zone and device local time zone, as well as methods for formatting date times.
AppLivecycle service listens for application/activity lifecycle state change and notifies the subscribed listeners for them. The app lifecycle states are defined in Flutter’s enum AppLifecycleState with values of resumed, inactive, paused, suspending. The subscribers to this service are mainly other services that need to handle awake from background lifecycle events (resume) in order to refresh data.
AppNavigation service listens for UI navigation stack events and notifies the subscribed listeners for them. The navigation events are defined in the AppNavigationEvent enum and they are push, pop, remove and replace. This service is used by Analytics that needs to always know which is the current panel at the top of the navigation stack, as well as to log panel navigation events.
Assets service provides access to a global shared static assets data. Assets contain sections for various modules. Most of these sections should be considered as constant data that is not expected to get changed like dining types, laundry locations, sport types, FlexUI service display rules or privacy levels and features.
Assets are loaded from a statically embedded resource file assets/asset.json, but this data could be overridden from assets on the Net.
Auth2 service maintains user authentication, account, profile and shared preferences using the Core BB backend services. The authentication types are defined in Auth2LoginType enumeration. There are 4 general authentication types supported in a Rokwire application: anonymous (not logged in), and OIDC, phone and email authentication. As soon as the application starts a new anonymous account is created. Later if the user logs in the Auth2 service switches to this user's account. If the user logs out the service switches back to the anonymous account created on startup.
OIDC login flow includes launching an external browser where the user can input securely its user name and password. On successful login the external browser returns the control in the application by deep link invocation and then the service access Core BB with the supplied token by the external browser.
Phone login is a two step process. On the first step the user inputs its phone number. The backend sends a verification code as a text message to that phone number that needs to be entered in the next step. After successful verification of this code the user is logged in.
When the user logs in by email for the first time it is required to enter the email address and a password. The backend sends a verification email to that email address. After this verification the user can use the email login credentials created on the first step. Consequent login by the same email requires just entering the email address and the password.
When the user logs in or when an anonymous account is created Core BB provides a token for this account. It is used to authenticate the network calls to the other backend services by applying an authentication header to the HTTP requests. These tokens has predefined durability and they expire after a given period of time. In that case, if an expired token is applied as authentication for a network call the response is 401 Unauthorized error. In this case Auth2 service uses the refresh API of Core BB that renews the token.
A user account contains profile data (Auth2UserProfile), shared preferences (Auth2UserPrefs), permissions, groups and roles. CoreBB supports different authentication types for single user account, that are described as Auth2Type lists in the account.
Config service maintains application configuration data. The config contains:
- Endpoint URLs for different backend services that the application uses.
- Different keys, tokens and accounts used to access rokwire or third party services. The non public entries are kept encrypted.
- Different application settings.
- Upgrade data that defines if a new version is available or if an upgrade is required.
On the very first app launch the config content is loaded from the backend and cached on local device storage. Then Config service maintains the cached data consistent and up to date by checking for updates on startup or after resigning in background for a given period of time.
Connectivity service monitors connection status and notifies listeners for changes. The subscribers to this service are UI content panels who need to handle offline state and display appropriate messages. Network service also checks connectivity status and in case of offline do not attempt to perform Http requests. Analytics service, who provides connectivity status in each packet, has its own handling for this, i.e. it is not based on Connectivity.
Content service provides tools for uploading images to Content BB. The name of this service is not quite appropriate and should get changed.
DeepLink service listens for external deep link invocations to the host application and fires notification in that case.
DeviceCalendar service provides interfaces for maintaining events on system (device) calendar service.
Events service provides access to Events backend service. It exposes interfaces for loading and filtering events by different criteria like user location, event category, date and time or tags. It provides interfaces for searching events as well as for creating an event or retrieving a particular event by id. Other interfaces in this service support retrieving global event categories and tags.
The only purpose of this service is to initialize the Firebase application in order to use different features from the Firebase plugins family.
FirebaseCrashlitycs service is a wrapper for Firebase Crashlytics support. It exposes crash reporting APIs which can be used by the application components. It internally calls the Firebase Crashlytics API.
FirebaseMessaging service provides access points to the Firebase Messaging SDK. It supports Firebase topics subscriptions APIs and listening for FCM notifications. In case FCM arrives it is handled and exposed for further processing at application level.
FlexUI service provides dynamic UI content depending on various factors like user roles, privacy level, group membership and so on. The UI content and the rules for content availability are defined as JSON in assets/flexUI.json. The service uses this JSON as an input and builds the current display content of the app. The service listens for updates in the other services that could affect the current display content and updates it in this case. The service provides capability to override the built in assets content on the net.
The supported rule types are:
- Boolean expressions for user roles;
- Boolean expressions for group membership;
- Required privacy level;
- Required authentication type or account role;
- Required platform (Android/iOS), environment (dev/production/test) or build (debug/release/profile);
GeoFence service monitors user location and determines whether it is inside a predefined region or not. The target regions are obtained from locations backend service. It uses native components for the region monitor (geoFence gateway from Rokwire plugin). It holds all regions that the user is currently inside and makes this available to the entire application at any time. This data is used to filter geofenced stadium polls, voter registration and MTD Bus pass.
In addition GeoFence service provides beacon ranging for a given beacon region. While a beacon region could match multiple beacons, ranging provides the particular beacons (in terms of UUID/minor/major) that are nearby the user. GeoFence service holds all nearby beacons while their regions are being ranging and this data is available to the entire application at any time. This functionality is used by MTD Bus Pass to detect the particular bus beacon.
Groups service exposes API for working with groups like query groups, administrate, post messages, apply or leave groups, etc. The service caches and keeps up to date all groups the user is a member of that is used by FlexUI service to filter UI content.
HttpProxy service is used to set HTTP proxy server and port that overrides all network flow for application level. This is part of debug features and available only for dev environment.
Inbox service provides API for notifications access and management. It allows retrieval of user's notifications, sending notification or deleting notifications. Inbox service works close with FirebaseMessaging service in order to provide the FCM token obtain by FirebaseMessaging service as well as maintenance of FCM topics subscription.
Localization service provides localized strings depending on the current device locale. It loads localized strings for statically embedded JSON files in app resources - assets/string.<language code>.json. This service also maintains the ability to override these data with strings from the Net.
LocationServices service provides access to location services status and monitors its updates. Subscribers to this service are UI elements whose content depends on whether the app has granted access to location services or not. Analytics service also depends on this service for location services status shared property.
Log service exposes log APIs which can be used by the application components as debug, warning, info, error etc.
Network service exposes APIs for creating HTTP requests. All other modules perform their HTTP activity through Network service. This allows it to control all network traffic in a single place and add common app features like offline checks or analytics logs.
Network service has defined an abstraction for HTTP request authorization, represented by NetworkAuthProvider class, that allows signing a HTTP request transparently in different ways and taking care of refreshing authorization tokens in case the request fails with authorization error.
Notification service provides an unified and abstract event subscription/notification model that follows the model of NSNotificationCenter iOS service.
Onboarding service implements the abstraction for onboarding flow based on FlexUI definitions. It provides the order of appearance of onboarding panels as well as which panel to show or not depending on the flow.
Polls service maintains currently opened (active) polls and access to user polls.
Each active poll is held in internal class _PollChunk. It contains as well as the poll object itself but also its internal status, and event stream subscription for listening for vote updates in this poll.
User’s polls are accessed by getMyPolls and getRecentPolls methods. They return a public PollsChunk class that holds the necessary data for paging the polls.
Storage service provides access to shared application preferences. All other modules do not work straight with SharedPreferences, they use Storage APIs instead so all shared preference access is controlled at a single place.
Storage service supports storing data in encrypted format that is used to store user sensitive data like tokens, PII, etc.
Storage service fires notifications when any user preference data gets updated that allow other to listen for this event and take appropriate actions in case of update.
Styles service provides mapping for UI elements like fonts or colors. The UI elements are associated keys. The UI requests a given resource by its key and Styles service provides the requested resource. This allows the same UI to vary by given UI elements across different applications and brandings.
The mapping is defined in assets/styles.json. This mapping could be overridden in the assets backend service.
TrackingServices service provides access to tracking services authorization status in iOS. It uses the AppTrackingTransparency library to query current authorization status and to request such. The tracking authorization is requested before displaying embedded web panel content.