e-mission phone app
This is the phone component of the e-mission system.
Additional Documentation
Additional documentation has been moved to its own repository e-mission-docs. Specific e-mission-phone wikis can be found here: https://github.com/e-mission/e-mission-docs/tree/master/docs/e-mission-phone
Issues: Since this repository is part of a larger project, all issues are tracked in the central docs repository. If you have a question, as suggested by the open source guide, please file an issue instead of sending an email. Since issues are public, other contributors can try to answer the question and benefit from the answer.
Updating the UI only
If you want to make only UI changes, (as opposed to modifying the existing plugins, adding new plugins, etc), you can use the new and improved (as of June 2018) e-mission dev app.
Installing (one-time)
Run the setup script
$ bash setup/setup_serve.sh
(optional) Configure by changing the files in www/json. Defaults are in www/json/*.sample
$ ls www/json/*.sample
$ cp www/json/startupConfig.json.sample www/json/startupConfig.json
$ cp ..... www/json/connectionConfig.json
Activation (after install, and in every new shell)
$ source setup/activate_serve.sh
Running
-
Start the phonegap deployment server and note the URL(s) that the server is listening to.
$ npm run serve .... [phonegap] listening on 10.0.0.14:3000 [phonegap] listening on 192.168.162.1:3000 [phonegap] [phonegap] ctrl-c to stop the server [phonegap] .... -
Change the devapp connection URL to one of these (e.g. 192.168.162.1:3000) and press "Connect"
-
The app will now display the version of e-mission app that is in your local directory
-
The console logs will be displayed back in the server window (prefaced by
[console]) -
Breakpoints can be added by connecting through the browser - Safari (enable develop menu): Develop -> Simulator -> index.html - Chrome: chrome://inspect -> Remote target (emulator)
Ta-da! www directory, the app will automatically be re-loaded without manually restarting either the server or the app
Note1: You may need to scroll up, past all the warnings about Content Security Policy has been added to find the port that the server is listening to.
End to end testing
A lot of the visualizations that we display in the phone client come from the server. In order to do end to end testing, we need to run a local server and connect to it. Instructions for:
- installing a local server,
- running it,
- loading it with test data, and
- running analysis on it
are available in the e-mission-server README.
In order to make end to end testing easy, if the local server is started on a HTTP (versus HTTPS port), it is in development mode. By default, the phone app connects to the local server (localhost on iOS, 10.0.2.2 on android) with the prompted-auth authentication method. To connect to a different server, or to use a different authentication method, you need to create a www/json/connectionConfig.json file. More details on configuring authentication can be found in the docs.
One advantage of using skip authentication in development mode is that any user email can be entered without a password. Developers can use one of the emails that they loaded test data for in step (3) above. So if the test data loaded was with -u [email protected], then the login email for the phone app would also be [email protected].
Updating the e-mission-* plugins or adding new plugins
Pre-requisites
- the version of xcode used by the CI
- to install a particular version, use xcode-select
- or this supposedly easier to use repo
- NOTE: the basic xcode install on Catalina was messed up for me due to a prior installation of command line tools. These workarounds helped.
- git
- the most recent version of android studio
- NOTE: although Catalina has a
/usr/bin/java, trying to run it gives the errorNo Java runtime present, requesting install.. The build now requires Java 11. Installed OpenJDK 11 (Temurin) using AdoptOpenJDK to be consistent with the CI.
- NOTE: although Catalina has a
Important
Most of the recent issues encountered have been due to incompatible setup. We have now:
- locked down the dependencies,
- created setup and teardown scripts to setup self-contained environments with those dependencies, and
- CI enabled to validate that they continue work.
If you have setup failures, please compare the configuration in the passing CI builds with your configuration. That is almost certainly the source of the error.
Installing (one time only)
Run the setup script for the platform you want to build
$ bash setup/setup_android_native.sh
AND/OR
$ bash setup/setup_ios_native.sh
(optional) Configure by changing the files in www/json. Defaults are in www/json/*.sample
$ ls www/json/*.sample
$ cp www/json/startupConfig.json.sample www/json/startupConfig.json
$ cp ..... www/json/connectionConfig.json
Activation (after install, and in every new shell)
$ source setup/activate_native.sh
Run in the emulator
$ npx cordova emulate ios
AND/OR
$ npx cordova emulate android
Creating logos
If you are building your own version of the app, you must have your own logo to avoid app store conficts. Updating the logo is very simple using the ionic cordova resources command.
Note: You may have to install the cordova-res package for the command to work
Troubleshooting
- Make sure to use
npx ionicandnpx cordova. This is because the setup script installs all the modules locally in a self-contained environment usingnpm installand notnpm install -g - Check the CI to see whether there is a known issue
- Run the commands from the script one by one and see which fails
- compare the failed command with the CI logs
- Another workaround is to delete the local environment and recreate it
- javascript errors:
rm -rf node_modules && npm install - native code compile errors:
rm -rf plugins && rm -rf platforms && npx cordova prepare
- javascript errors:
Beta-testing debugging
If users run into problems, they have the ability to email logs to the maintainer. These logs are in the form of an sqlite3 database, so they have to be opened using sqlite3. Alternatively, you can export it to a csv with dates using the bin/csv_export_add_date.py script.
<download the log file>
$ mv ~/Downloads/loggerDB /tmp/logger.<issue>
$ pwd
.../e-mission-phone
$ python bin/csv_export_add_date.py /tmp/loggerDB.<issue>
$ less /tmp/loggerDB.<issue>.withdate.log
Contributing
Add the main repo as upstream
$ git remote add upstream https://github.com/covid19database/phone-app.git
Create a new branch (IMPORTANT). Please do not submit pull requests from master
$ git checkout -b mybranch
Make changes to the branch and commit them
$ git commit
Push the changes to your local fork
$ git push origin mybranch
Generate a pull request from the UI
Address my review comments
Once I merge the pull request, pull the changes to your fork and delete the branch
$ git checkout master
$ git pull upstream master
$ git push origin master
$ git branch -d mybranch
| 
|
| 
|
| 
|
| 
| 
|
| 
|
| 
| 
|
| 
|
| 
| 
|
| 
|
| 
|
| 
| 
|
| 
| 
|
| 
| 
|
| 
| 
|
| 
|
| 
| 
|
| 
| 
|
| 
|
5 Aug 17, 2021
1 Oct 29, 2021
65 Nov 15, 2022
90 Dec 29, 2022
441 Dec 24, 2022
8.3k Jan 5, 2023
44 Nov 20, 2022
1.1k Jan 2, 2023
94 Mar 25, 2022
29 Oct 8, 2022
4.3k Jan 2, 2023
6 May 13, 2022
6 Sep 20, 2022
4 Dec 15, 2022
113 Nov 21, 2022
24 Nov 11, 2021
0 Dec 30, 2021
0 Nov 19, 2021
5.5k Dec 22, 2022
207 Dec 22, 2022