A hybrid mobile application to actively capture data for the RADAR-Base Platform.
We use the Ionic framework, which is built with Angular and wraps Apache Cordova.
It is recommended that you install the following versions or later:
node v16.13.0
ionic v5.4.16
npm v8.1.0
First install Node.js and Yarn.
Globally install ionic and cordova:
$ npm i -g ionic cordova
In the project folder run npm i to install dependencies:
$ npm i
Cordova provides a simple command to install the plugins and platforms set in package.json or config.xml.
$ cordova prepare
To run the application in the browser use:
$ ionic serve
Use the following command to sort, format and fix common css problems:
$ npm run fix:css
Use the following command before commiting to fix all common styling and sorting problems:
$ npm run fix:all
In order to add platforms to target, you must install the required SDKs.
To add the Android platform, you need to have the Android SDK pre installed. This step also adds the plugins listed in config.xml to the project.
$ ionic cordova platform add android
Run the app in an Android device:
$ ionic cordova run android
Run the app in an Android emulator:
$ ionic cordova emulate android
To add the iOS platform, you need to have XCode pre installed.
$ ionic cordova platform add ios
Run the app in an iOS device:
$ ionic cordova run ios
If using Firebase for notifications, analytics, or remote config, create your Firebase project. Then, add your iOS or Android app to the Firebase project. Once added, please download the app's google-services.json file (for Android) and GoogleService-Info.plist (for iOS), and add it to the root directory.
When you add your iOS or Android app to the Firebase project, make sure you name your package name as app-id
- Android :
org.phidatalab.radar_armt - iOS:
org.phidatalab.radar-armt
If using FCM pull notifications instead of the local ones, please specify the FCM sender id (as mentioned in FCM settings) in src/assets/data/defaultConfig.ts and the default notification type to FCM (this is already the default value).
export const FCMPluginProjectSenderId = 'your-sender-id'
export const DefaultNotificationType = 'FCM'In order for notifications to be sent, you must run your own app server. It is part of the RADAR-base stack, and specific docs can be found here.
For Android remote notifications, setting your sender ID and adding your google-services.json file is enough to begin receiving notifications. However, for iOS notifications, you must add either an APNs authentication key or APNs certificate to connect with Apple Push Notifications. This can be added in the Firebase project's Cloud Messaging settings.
Certain values can be overriden using Firebase Remote Config. Specifically, the following variables are supported:
| Parameter | Description | Default value |
|---|---|---|
oauth_client_id |
Client ID to connect to the ManagementPortal with | aRMT |
oauth_client_secret |
Client secret to connect to the ManagementPortal with | `` |
oauth_refresh_seconds |
After how many seconds to refresh the OAuth token | 1800 (=30 minutes) |
protocol_repo |
Github repo where the protocol definitions are located. | RADAR-Base/RADAR-aRMT-protocols |
protocol_branch |
Github branch where the protocol definitions should be read from | master |
protocol_path |
Path inside a project name that should be read for a protocol | protocol.json |
kafka_specification_url |
URL of the Kafka topic specification | https://api.github.com/repos/RADAR-base/radar-schemas/contents/specifications/active/aRMT-1.4.3.yml?ref=master |
platform_instance |
Title of RADAR Base / platform instance | RADAR-CNS |
participant_attribute_order |
Map that specifies the order in which the attributes are matched with the protocol path | {Human-readable-identifier: -1} |
schedule_year_coverage |
Schedule coverage in years (length of schedule to generate tasks until) | 3 |
notification_messaging_type |
Notifications type (either 'FCM_REST' or 'LOCAL' notifications) | FCM_REST |
app_server_url |
Default app server url. | {DefaultEndPoint + '/appserver'} |
github_fetch_strategy |
Default Github fetch strategy for Github requests (default or appserver). | default |
app_credits_title |
Title of the popup box that appears when you tap on the app logo on the left hand side of the homepage. | Credits |
app_credits_body |
Body of the popup box that appears when you tap on the app logo on the left hand side of the homepage. | Made with ♥ for you by the RADAR-Base community. |
auto_next_questionnaire_types |
String list of question/question input types where the questionnaire will automatically move to the next question upon answering the question. It is recommended to always include timed and audio types. | timed,audio |
skippable_questionnaire_types |
String list of question/question input types where the next button is enabled by default, allowing the question to be skippable. | audio |
show_task_calendar_name |
The task calendar by default shows the task timestamp instead of the task name. This allows showing of the task name instead of the timestamp. | false |
show_task_progress_count |
In the questionnaire page, by default, only the task progress bar is shown. This config will enable the showing of the "question number / total questions" count. | false |
Conditions can be added to remote config variables to target specific groups of users. Different condition rule types are supported: app, platform, country/region, user property, date/time, and random percentile. For example a protocol_branch config value can be different based on the user property projectId.
A user/subject can have attributes which are taken from Management Portal. These could determine what protocol would be pulled for the user from Github (RADAR aRMT Protocols). The repository should follow the format: /PROJECT_NAME/ATTRIBUTE-KEY/ATTRIBUTE-VALUE/protocol.json. Please note that a default protocol.json file must always be present in the project directory, e.g.: /PROJECT_NAME/protocol.json.
If multiple attributes are present for the user, the participant_attribute_order from the Remote Config will be used to determine which attribute takes precedence. If this is not present, the default value is {Human-readable-identifier: -1}; the human readable id will always be the highest priority. If an order value is not present for the attribute, the default value (MAX_INT_VALUE) would be used.
In order to personalize Firebase events and remote config variables, certain user properties may be added to the Firebase console. Specifically, the following user properties are supported:
| Property | Description |
|---|---|
subjectId |
Custom identifier for the user |
humanReadableId |
Human readable identifier for the user |
baseUrl |
Custom identifier for the base URL of the project |
projectId |
Custom identifier for the project that a user belongs to |
sourceId |
Custom identifier for the source the application is registered as |
enrolmentDate |
Enrolment date of the user |
Further details on the events that are already logged, default events, and default user properties can be found on the RADAR Base wiki pages.
You can change the default config locally in src/assets/data/defaultConfig.ts. Some of these can also be modified in Firebase remote config.
The main configs you may want to modify are:
The client secret for OAuth authorisation with the Management Portal (empty by default).
export const DefaultOAuthClientSecret = ''The default endpoint of where the RADAR-base platform is hosted.
export const DefaultEndPoint = 'https://your-hosted-radar-platform-base-url/'The default appserver configs.
// The notification type (either 'FCM_REST' or 'LOCAL' notifications, NOTE: 'FCM_XMPP' support was removed in v2.6.4)
export const DefaultNotificationType: string = 'FCM_REST'
// App server URL
export const DefaultAppServerURL = DefaultEndPoint + '/appserver'You can also change the default Github source details where the questionnaire scheduling protocols and questionnaire schemas are hosted.
// The Github repository where the protocols are located
export const DefaultProtocolGithubRepo = 'RADAR-Base/RADAR-aRMT-protocols'
// The name of the branch in the protocol repository
export const DefaultProtocolBranch = 'master'
// The name of the repository where the questionnaire schemas are located
export const DefaultSchemaGithubRepo = 'RADAR-Base/RADAR-Schemas'
// The name of the branch in the schema repository
export const DefaultSchemaBranch = 'master'
// The Github content fetching mechanism, if this is done by a direct request to Github or a request through the app server. (REMOTE CONFIG KEY: `github_fetch_strategy`, VALUES: `default` (direct to Github) or `appserver`)
export const DefaultGithubFetchStrategy = 'default'Translations must be specified or modified in the localisations file (src/assets/data/localisations.ts). When adding additional text in the localisations file, additional keys must also be added to src/app/shared/enums/localisations.ts.
To add additional languages, the following default config (src/assets/data/defaultConfig.ts) variable must be updated:
export const DefaultSettingsSupportedLanguages: LanguageSetting[] = []Instructions to build a signed apk for publishing on the playstore -
- Clone the aRMT project from github.
- Configure it as per instructions above.
- Run the following to build the app
npm install
npm run build
ionic cordova platform add android
ionic cordova build --release android- This will generate an apk at
<your-project-path>/platforms/android/app/build/outputs/apk/release/app-release-unsigned.apk - Create a keystore for signing the apk. Keep this safe as this is tied to your play releases and only apks signed by this can be released to the playstore after the intitial release.
- You will need to then sign this apk using jarsigner
jarsigner -verbose -sigalg SHA1withRSA -digestalg SHA1 -storepass <your-keystore-pass> -keystore <your-keystore-path> <your-project-path>/platforms/android/app/build/outputs/apk/release/app-release-unsigned.apk alias_name;
- Then you will need to align the apk using zipalign (https://developer.android.com/studio/command-line/zipalign) like-
$ANDROID_HOME/build-tools/27.0.2/zipalign -v 4 <your-project-path>/platforms/android/app/build/outputs/apk/release/app-release-unsigned.apk <your-project-path>/platforms/android/app/build/outputs/apk/release/radar-armt-app-$APP_VERSION.apk;
- Now the apk is ready to be uploaded to the playstore at path
<your-project-path>/platforms/android/app/build/outputs/apk/release/radar-armt-app-$APP_VERSION.apk - NOTE: The signing and aligning can also be done by importing the android project at path
<your-project-path>/platforms/android/into Android Studio.
The questionnaire input types supported are audio, checkbox, descriptive, info-screen, matrix-radio, radio, range-info, range-input, slider, text, date, time, and timed-test.
The descriptive input supports HTML in the field_label property of a questionnaire in the questionnaire definition. The css will automatically be inherited from the app. Here is an example input:
Hello this is an example of a descriptive input text.
<br> <br>
<b>This is a bold text</b>
<br>
<h1>This is an h1</h1>
<br>
<h2>This is an h2</h2>
<br>
<h3>This is an h3</h3> <h4>This is an h4</h4> <h5>This is an h5</h5>
<br>
<iframe width="560" height="315" src="https://www.youtube.com/embed/4rxh60G2RRU" title="YouTube video player" allowfullscreen></iframe>
<br><br>
This is an example of an image:
<br>
<img src="https://images.pexels.com/photos/1108099/pexels-photo-1108099.jpeg">
Here is the output:
Here are some common errors you might find during installation.
When you are running ionic cordova run ios, you might encounter the problem, we solved this problem by refering this issue with cordova-custom-config.
We enter the following command at the root directory.
cd plugins/cordova-custom-config
npm install