Merge pull request #2255 from IDEMSInternational/docs/new-android-wor…

…kflows

docs: Android config workflows

cspell.config.yml

@@ -21,6 +21,7 @@
     "matomo",
     "metabase",
     "mkdocs",
+    "mycompany",
     "nocheck",
     "Nouislider",
     "overidden",

documentation/docs/developers/android-assets.md

@@ -13,7 +13,7 @@ The splash image must be at least 2732×2732px. The static icon image must be at
 |![](./images/splash.png)|![](./images/icon.png)|![](./images/icon-background.png)|![](./images/icon-foreground.png)|
 
 
-## Generating splash screens and app icons
+## Configuring splash screens and app icons
 With `.png` files provided from which to generate the splash screen and app icons, their paths must be provided in the deployment `config` defined in the `.config.ts` file (see [Deployment Configuration](../deployments/) for a specification of this file). These paths are relative the root directory.
 
 For example:
@@ -33,11 +33,17 @@ const config: IDeploymentConfig = {
 };
 ...
 ```
-To generate the android assets, run
+## Generating Android assets through Github
+With the assets correctly configured as above, the splash screen and launch icon will automatically be generated when the `Android - Release to Google Play` action is run.
+
+## Generating Android assets locally
+To generate the android assets locally, run
 ```sh
 yarn workflow android
 ```
-Or, to generate just the splash screens or just the app icons, run
+This will also populate the Android configuration files with the values of `app_id` and `app_name` as specified in the [deployment config](./deployments.md#android-app-management).
+
+Alternatively, to generate just the splash screens or just the app icons, run
 ```sh
 yarn workflow android set_splash_image
 ```

documentation/docs/developers/deployments.md

@@ -86,6 +86,7 @@ const config: IDeploymentConfig = {
   name: "example",
   git: {
     content_repo: "https://github.com/my-org/my-git-repo",
+    content_tag_latest: "1.0.0",
   },
 ```
 
@@ -142,9 +143,80 @@ If for any reason the local content repo gets into a bad/conflicted state, it ca
 The content repo can be opened via shortcut `yarn workflow repo open`
 
 
+## Android Management
+For deployments that are intended to be published to the Google Play Store, some additional configuration is required.
 
+### App ID and App Name
+The App ID uniquely identifies an Android app on devices and in the Google Play Store (see the official [Android developer docs](https://developer.android.com/build/configure-app-module#set-application-id) for more details). It is common to use the segments to identify your organisation and app in a reverse-dns format, e.g. `international.idems.my_example_app`, or `com.mycompany.example_app`.
+
+!!! warning
+    Android app IDs must contain at least 2 segments (one or more dots) and once set cannot be changed. So consider carefully how the id may be used in the future to represent your app. 
+
+
+The App Name is the name that will be displayed to users on devices and in the Google Play Store.
+
+These values must be set in the deployment config before the app can be built as an Android bundle.
+
+For example:
+```ts
+config.android.app_id = "international.idems.my_example_app";
+config.android.app_name = "My Example App";
+```
+
+### Versioning
+In order to build for Android, the deployment config must contain a valid value for the property `config.git.content_tag_latest` (see [Github management](#github-management)). This value can be changed manually, or via the command:
+```sh
+yarn scripts version --content (--auto-patch)
+```
+
+### Google Services
+Connecting to Firebase is currently required by all Android apps. Follow the instructions for [Firebase management](#firebase-management) for native platforms in order to set this up for a new deployment.
+
+### Generating an app icon and splash screen
+See [Android Assets](./android-assets.md).
+
+## Firebase management
+Firebase is used to provide some services such as authentication and crashlytics. Currently, even apps that do not use these services explicitly must be linked to a corresponding Firebase project in order to be built for native devices. Exclusively local and web deployments do not require Firebase to be configured, unless they make use of these features.
+
+### Native platforms
+For apps that target Android, a corresponding "Android app" should be added to a linked Firebase project, with an `Android package name` matching the `app_id` for the deployment (see [Android Management](#android-management)). The relevant `google-services.json` file should be downloaded, and copied to `android/app/google-services.json` for building the Android app locally, or its contents copied into a `GOOGLE_SERVICES_JSON` secret in the deployment's Github repo, for building the Android app via github action.
+
+### Enabling Firebase features
+To enable Firebase features, a Firebase config must be included in the deployment config. 
+
+In accordance with the instructions on deployment [file encryption](#file-encryption):
+
+1. If the deployment does not already have a `encrypted` folder, run `yarn workflow deployment encrypt` to create one.
+2. Create a new file in the `encrypted` folder called `firebase.json`, and populate the file with the JSON representation of the `firebaseConfig` object associated with the target app, available from the Project Settings section of the Firebase console.
+	- e.g. 
+
+    ```json
+    {
+      "apiKey": "...",
+      "authDomain": "...",
+      "databaseURL": "...",
+      "projectId": "...",
+      "storageBucket": "...",
+      "messagingSenderId": "...",
+      "appId": "...",
+      "measurementId": "..."
+    }
+    ```
+
+3. Run `yarn workflow deployment encrypt` to encrypt this file. 
+4. The deployment config will then need to be updated to include the following:
+
+    ```js
+    import { loadEncryptedConfig} from "scripts";
     
-   
+    config.firebase = {
+      config: loadEncryptedConfig('firebase.json'),
+      auth: { enabled: true },
+      crashlytics:{ enabled: true }
+    }
+    ```
+   where enabling the various features is optional.
+
 ## File Encryption
 In cases where deployments need to share private information, such as API keys or service accounts, a special encryption folder can be used to handle encryption and decryption processes
 

documentation/docs/developers/in-app-updates.md

@@ -53,8 +53,8 @@ Manually delete folders from `www\assets\app_data\assets` to reduce size for eas
 
 2. Sync to android and open in android studio
 ```
-npx cap sync
-npx cap open
+npx cap sync android
+npx cap open android
 ```
 
 3. Create a debug build from android studio menu (assumes google.json populated locally)
@@ -68,7 +68,10 @@ _Build -> Build Bundles / APKs -> Build Bundle_
 
 6. Download the app from the internal link created. 
 
-7. Increase version (defined in deployment config `git.content_tag_latest`) and repeat steps 1-4
+7. Increase version (defined in deployment config `git.content_tag_latest`) and repeat steps 1-4. Increasing the version can be achieved by manually updating the deployment config file, or via the command
+```sh
+yarn run version --content
+```
 
 8. Follow link to new internal update but do not install (assume this makes device aware of potential update instead of waiting for store periodic check)
 

documentation/docs/developers/quickstart.md

@@ -17,13 +17,18 @@ The main tech stack comprises of:
 
 1. Install Android Studio (https://developer.android.com/studio)
 2. Install Android SDK Tools (26.0.1 or greater), as illustrated here: https://capacitorjs.com/docs/android#getting-started
-3. Build the project locally and sync android files
+3. Ensure that the active deployment is fully configured in accordance with the requirements detailed in [Android app management](./deployments.md#android-app-management).
+4. To populate the Android build files with the app ID, app name and version number (`content_tag_latest`) defined in the deployment config, run
+   ```sh
+   yarn workflow android configure
    ```
-   $yarn build
-   $npx cap sync
+5. Build the project locally and sync android files
+   ```sh
+   yarn build
+   npx cap sync android
    ```
-4. Open the project in Android Studio `npx cap open android`
-5. From Android studio you can manage the app build, emulate and run processes, as illustrated here: https://capacitorjs.com/docs/android#running-your-app
+6. Open the project in Android Studio `npx cap open android`
+7. From Android studio you can manage the app build, emulate and run processes, as illustrated here: https://capacitorjs.com/docs/android#running-your-app
 
 Android studio should handle the process of downloading required tools, find below guidance for manual configuration.