Skip to content
Snippets Groups Projects
Commit cb589333 authored by Lene Wasskog's avatar Lene Wasskog
Browse files

doc: Add ios specific documentation, format text

parent e78a8ff2
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
Showing
with 69 additions and 46 deletions
README.md
+ 69
− 46
View file @ cb589333
......@@ -5,37 +5,43 @@
Providing an easy way to register pest observations made in the field by registered VIPS users. Available for Android and iOS smartphones.
## Architecture
The app has been built using
* [Apache Cordova](https://cordova.apache.org/) v.11.0.0
* [Vue.js version 2](https://v2.vuejs.org/) and [vue-cli](https://cli.vuejs.org/)
The app has been built using
- [Apache Cordova](https://cordova.apache.org/) v.12.0.0
- [Vue.js version 2](https://v2.vuejs.org/) and [vue-cli](https://cli.vuejs.org/)
Most of the UI has been built in vue, and then compiled to the cordova www folder, and then subsequently used to build for the smartphone platforms.
## Prerequisites: node, npm, vue-cli and cordova
Make sure you have the correct versions of npm and nodejs
Use nvm to install, here's [how to install nvm in the first place](https://github.com/nvm-sh/nvm#installing-and-updating)
Then run:
``` bash
```bash
nvm install --lts
sudo npm install -g @vue/cli --unsafe-perm
sudo npm install -g cordova --unsafe-perm
```
sudo npm install -g cordova@12.0.0 --unsafe-perm
```
## Build Setup (vuejs)
You need to add your local configuration file before you do this. The file's name must be `src/components/CommonUtilLocal.vue`, and here's example content:
```html
<script>
export default {
CONST_URL_DOMAIN : 'https://logic.vips.nibio.no',
CONST_DEBUG : false
}
export default {
CONST_URL_DOMAIN: "https://logic.vips.nibio.no",
CONST_DEBUG: false,
};
</script>
```
Then you can install the dependencies and run the test web server
``` bash
```bash
# install dependencies
npm install
......@@ -53,25 +59,30 @@ For a detailed explanation on how things work, check out the [guide](http://vuej
## Build/emulate with cordova
``` bash
# Add browser and android platforms (haven't tested iOS yet)
```bash
# Add browser, android and ios platforms
cordova platform add browser
cordova platform add android
cordova platform add ios
# Test in browser
cordova emulate browser
# Test on Android. Requires correct setup of the Android SDK.
# Test on Android. Requires correct setup of the Android SDK.
# Read more here: https://cordova.apache.org/docs/en/latest/guide/platforms/android/index.html
cordova emulate android
# Test on IOS. Install Xcode from Mac AppStore, and the iOS Simulator
cordova emulate ios
```
### Troubleshooting Android platform builds
* If you upgrade cordova or change the package name of the app (in config.xml),
you should reset the platform, using `cordova platform remove android` and then `cordova platform add android`
- If you upgrade cordova or change the package name of the app (in config.xml),
you should reset the platform, using `cordova platform remove android` and then `cordova platform add android`
#### Error message when starting the Android emulator
(When running `cordova emulate android`)
```
......@@ -83,9 +94,8 @@ This can be solved by installing the Android command-line tools, as [per these i
![How to install Android CLI tools](./document/images/android_sdk_cli_tools.png "How to install Android CLI tools")
### Connecting to a local server
While developing, you will want to connect to a local instance of VIPSLogic. This is done by editing the property `CONST_URL_DOMAIN` in `/src/components/CommonUtilLocal.vue`. Set it to whatever domain name you wish (e.g. vipslogic-local.no) and then edit your `/etc/hosts` file to point this to the IP address 10.0.2.2, like this
```
......@@ -94,26 +104,28 @@ While developing, you will want to connect to a local instance of VIPSLogic. Thi
## Test on an Android phone
After running `npm run build`, you can find the Android package (`.apk`) in `/platforms/android/app/build/outputs/apk`.
By connecting your Android phone to your computer and copying the file to your phone, you can install it on the phone. **This
depends on you having enabled developer mode on your phone**. How to do that differs a great deal, so search the interwebs for
After running `npm run build`, you can find the Android package (`.apk`) in `/platforms/android/app/build/outputs/apk`.
By connecting your Android phone to your computer and copying the file to your phone, you can install it on the phone. **This
depends on you having enabled developer mode on your phone**. How to do that differs a great deal, so search the interwebs for
how to do it.
## Develop the code
### Don't touch the /www folder!
Normally in Cordova you would put your code here, but this is where vue-cli is putting the things that it builds.
Normally in Cordova you would put your code here, but this is where vue-cli is putting the things that it builds.
### Where to update app version
* `/package.json` (Updates version in the Settings/About section in the app)
* `/config.xml`
- `/package.json` (Updates version in the Settings/About section in the app)
- `/config.xml`
### Main template
The main layout is based on a very simple template snatched from Bootstrap. You find it in /html (at the project root level).
Everything that Vuejs operates on happens inside the `main` element
``` html
```html
<main id="app" role="main" class="container"></main>
```
......@@ -124,18 +136,19 @@ Looking at /src/main.js, the Vue app is not started until Cordova fires the devi
The router components (the "pages" in the Single Page Application that you manage) are found in `/src/components`. The router (paths + components definitions) is found in `/src/router/index.js`
### Checking out new code
Remember to always run `npm install` after checking out new code from the repository. That way, new dependencies will be installed.
### Translation
[This tutorial](https://www.codeandweb.com/babeledit/tutorials/how-to-translate-your-vue-app-with-vue-i18n) has been used to enable translation.
I couldn't get the per-component translation thing working (where you embed it in `<i18n>` tags),
so all translations go into the `/locales/[languagecode].json` files.
There's a simple translation example in `/src/components/PlacesList.vue`:
``` html
```html
<template>
<div>
<!-- ... -->
......@@ -151,21 +164,26 @@ There's a simple translation example in `/src/components/PlacesList.vue`:
Change the startup language in the app here in `/i18n.js`:
``` javascript
```javascript
export default new VueI18n({
locale: process.env.VUE_APP_I18N_LOCALE || 'nb', // Here you can customize
fallbackLocale: process.env.VUE_APP_I18N_FALLBACK_LOCALE || 'en',
messages: loadLocaleMessages()
})
locale: process.env.VUE_APP_I18N_LOCALE || "nb", // Here you can customize
fallbackLocale: process.env.VUE_APP_I18N_FALLBACK_LOCALE || "en",
messages: loadLocaleMessages(),
});
```
To translate in JavaScript, refer as `this.$i18n.t`, e.g.:
``` javascript
lstPOI.push({pointOfInterestId:'undefined',name: this.$i18n.t("mapobservation.label.noPOIselected")});
```javascript
lstPOI.push({
pointOfInterestId: "undefined",
name: this.$i18n.t("mapobservation.label.noPOIselected"),
});
```
### Adding Internationalization
``` bash
### Adding Internationalization
```bash
npm install vue-i18n --save
```
......@@ -188,6 +206,7 @@ emulator -avd Pixel_3a_API_30_x86 -wipe-data
Replace your emulator name with the example above
## Android publishing
Before building, signing and publishing, make sure you bump the version in `package.json`
```json
......@@ -204,6 +223,7 @@ Before building, signing and publishing, make sure you bump the version in `pack
"start": "npm run dev"
},
```
...and in config.xml
```xml
......@@ -218,20 +238,21 @@ Before building, signing and publishing, make sure you bump the version in `pack
For NIBIO, a signing key was originally created sometime in 2021, but it has been lost. After contacting Google Play Developer Support, we received instructions for how to generate a new key (example code):
``` bash
```bash
keytool -genkeypair -alias upload -keyalg RSA -keysize 2048 -validity 9125 -keystore keystore.jks
```
...so we did this, and stored the keystore *securely* (in a dev project folder)
...so we did this, and stored the keystore _securely_ (in a dev project folder)
We then extracted the PEM to send to Google (example code)
``` bash
```bash
keytool -export -rfc -alias upload -file upload_certificate.pem -keystore keystore.jks
```
Signing can be done like this (example):
``` bash
```bash
$ cordova run android --release -- --keystore=[PATH_TO_KEYSTORE] --storePassword=[KEYSTORE_PASSWORD] --alias=upload --password=[PASSWORD] --packageType=bundle
```
......@@ -248,14 +269,14 @@ https://developer.android.com/guide/app-bundle
https://developer.android.com/studio/publish#unknown-sources
## iOS Publishing
On iOS, do the regular `npm run build`, and then `cordova build ios`. You should then be ready to run the app in a simulator or a real device in XCode. Remember that in order to run it on a real device, you must sign it (see XCode screenshot below) with either your personal team account (for debug only) or a company account for distributing to App Store.
![Signing an app in XCode](./document/images/ios_signing.png "Signing an app in XCode")
### Distributing
In XCode, click `Product -> Archive`, and then select the latest build and Distribute. Click all sorts of yesses and hope for the best.
![Archive](./document/images/Xcode-archive.png "Archive")
......@@ -263,7 +284,8 @@ In XCode, click `Product -> Archive`, and then select the latest build and Distr
![Success](./document/images/Xcode-distribute-success.png "When everything goes according to plan")
### Versioning
You set the main version in `/config.xml` and `package.json` (in the source code, before building for iOS) - that's what's going to show in TestFlight/App store.
You set the main version in `/config.xml` and `package.json` (in the source code, before building for iOS) - that's what's going to show in TestFlight/App store.
![TestFlight](./document/images/testflight.png "TestFlight")
......@@ -272,6 +294,7 @@ However, you can update the **build** in TestFlight without changing the common
![XCode build version](./document/images/Xcode-build-versjon.png "XCode build version")
### Enabling developer mode
#### iOS 16
[This is how you do it](https://developer.apple.com/documentation/xcode/enabling-developer-mode-on-a-device)
[This is how you do it](https://developer.apple.com/documentation/xcode/enabling-developer-mode-on-a-device)
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment