From 2f7bb892e4c4b3d73b2ae80ddb1e3bfae9a43273 Mon Sep 17 00:00:00 2001 From: Johnny McQuade Date: Mon, 25 Mar 2024 10:00:01 +0000 Subject: [PATCH 1/6] docs: Android config workflows --- .../docs/developers/android-assets.md | 18 +++-- documentation/docs/developers/deployments.md | 66 ++++++++++++++++++- .../docs/developers/in-app-updates.md | 6 +- documentation/docs/developers/quickstart.md | 16 +++-- documentation/docs/index.md | 11 ---- 5 files changed, 91 insertions(+), 26 deletions(-) diff --git a/documentation/docs/developers/android-assets.md b/documentation/docs/developers/android-assets.md index 93821c06b..389efce74 100644 --- a/documentation/docs/developers/android-assets.md +++ b/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,17 +33,23 @@ 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 populate_android_assets +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 set_splash_image +yarn workflow android set_splash_image ``` or ```sh -yarn workflow set_launcher_icon +yarn workflow android set_launcher_icon ``` respectively. diff --git a/documentation/docs/developers/deployments.md b/documentation/docs/developers/deployments.md index 6530b0f8c..b17ef7e3e 100644 --- a/documentation/docs/developers/deployments.md +++ b/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,72 @@ 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). 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 manualy, 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 diff --git a/documentation/docs/developers/in-app-updates.md b/documentation/docs/developers/in-app-updates.md index 98ac15fb8..c7d09ac98 100644 --- a/documentation/docs/developers/in-app-updates.md +++ b/documentation/docs/developers/in-app-updates.md @@ -68,9 +68,9 @@ _Build -> Build Bundles / APKs -> Build Bundle_ 6. Download the app from the internal link created. -7. Increase version and repeat steps 1-4 -``` -yarn run version --android +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) diff --git a/documentation/docs/developers/quickstart.md b/documentation/docs/developers/quickstart.md index 9fd201284..a4f557195 100644 --- a/documentation/docs/developers/quickstart.md +++ b/documentation/docs/developers/quickstart.md @@ -17,13 +17,19 @@ 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 mangement](./deployments.md#android-app-management). +4. To populate the Android build files with the app ID and app name defined in the deployment config, run + ```sh + yarn workflow android configure ``` - $yarn build - $npx cap sync +5. To populate a +6. Build the project locally and sync android files + ```sh + yarn build + npx cap sync ``` -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 +7. Open the project in Android Studio `npx cap open android` +8. 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. diff --git a/documentation/docs/index.md b/documentation/docs/index.md index cb0736365..d9dece026 100644 --- a/documentation/docs/index.md +++ b/documentation/docs/index.md @@ -41,17 +41,6 @@ You will be prompted to specify the deployment type, this should be a `New Local See [Deployment Documentation](./developers/deployments.md) for more information about configuring deployments -### Firebase -To be able to run the full project a specific configuration file needs to be included to access -the online database and authentication methods. -``` -$ cp src/environments/firebaseConfig.sample.ts src/environments/firebaseConfig.ts -``` -The default file is blank and so some features may not be available (e.g. testing google sign-in) -It can be replaced with a version requested from the dev team. - -(Note - this process will likely be simplified in the future) - ## Running locally ### Start the local server From c1a60b6741996747d8b844839e63c9da6c444fcd Mon Sep 17 00:00:00 2001 From: Johnny McQuade Date: Mon, 25 Mar 2024 10:09:42 +0000 Subject: [PATCH 2/6] docs: tidy --- documentation/docs/developers/quickstart.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/documentation/docs/developers/quickstart.md b/documentation/docs/developers/quickstart.md index a4f557195..3790eca3b 100644 --- a/documentation/docs/developers/quickstart.md +++ b/documentation/docs/developers/quickstart.md @@ -18,18 +18,17 @@ 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. Ensure that the active deployment is fully configured in accordance with the requirements detailed in [Android app mangement](./deployments.md#android-app-management). -4. To populate the Android build files with the app ID and app name defined in the deployment config, run +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 ``` -5. To populate a -6. Build the project locally and sync android files +5. Build the project locally and sync android files ```sh yarn build npx cap sync ``` -7. Open the project in Android Studio `npx cap open android` -8. 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. From 695c2d402e8286f73490577e0e1f77a9dc393d19 Mon Sep 17 00:00:00 2001 From: Johnny McQuade Date: Mon, 25 Mar 2024 10:23:30 +0000 Subject: [PATCH 3/6] docs: spellcheck --- documentation/docs/developers/deployments.md | 2 +- documentation/docs/developers/quickstart.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/documentation/docs/developers/deployments.md b/documentation/docs/developers/deployments.md index b17ef7e3e..f3bb2b92b 100644 --- a/documentation/docs/developers/deployments.md +++ b/documentation/docs/developers/deployments.md @@ -156,7 +156,7 @@ 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 manualy, or via the command: +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) ``` diff --git a/documentation/docs/developers/quickstart.md b/documentation/docs/developers/quickstart.md index 3790eca3b..b79b730ca 100644 --- a/documentation/docs/developers/quickstart.md +++ b/documentation/docs/developers/quickstart.md @@ -17,7 +17,7 @@ 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. Ensure that the active deployment is fully configured in accordance with the requirements detailed in [Android app mangement](./deployments.md#android-app-management). +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 From 685d24e3bfbfaea697f34ec344597f9a527f23af Mon Sep 17 00:00:00 2001 From: Johnny McQuade Date: Tue, 26 Mar 2024 16:30:58 +0000 Subject: [PATCH 4/6] docs: added details re android app id --- documentation/docs/developers/deployments.md | 10 +++++++++- documentation/docs/developers/in-app-updates.md | 4 ++-- documentation/docs/developers/quickstart.md | 2 +- 3 files changed, 12 insertions(+), 4 deletions(-) diff --git a/documentation/docs/developers/deployments.md b/documentation/docs/developers/deployments.md index f3bb2b92b..a5edab7e0 100644 --- a/documentation/docs/developers/deployments.md +++ b/documentation/docs/developers/deployments.md @@ -147,7 +147,15 @@ The content repo can be opened via shortcut `yarn workflow repo open` 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). 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. +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 diff --git a/documentation/docs/developers/in-app-updates.md b/documentation/docs/developers/in-app-updates.md index c7d09ac98..99e3fdbe0 100644 --- a/documentation/docs/developers/in-app-updates.md +++ b/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) diff --git a/documentation/docs/developers/quickstart.md b/documentation/docs/developers/quickstart.md index b79b730ca..364f88def 100644 --- a/documentation/docs/developers/quickstart.md +++ b/documentation/docs/developers/quickstart.md @@ -25,7 +25,7 @@ The main tech stack comprises of: 5. Build the project locally and sync android files ```sh yarn build - npx cap sync + npx cap sync android ``` 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 From a827257eb56725ffc5893914d2a6e0b26cba34b1 Mon Sep 17 00:00:00 2001 From: chrismclarke Date: Tue, 26 Mar 2024 21:51:45 -0700 Subject: [PATCH 5/6] chore: update cspell --- cspell.config.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/cspell.config.yml b/cspell.config.yml index a837b998c..202631cbb 100644 --- a/cspell.config.yml +++ b/cspell.config.yml @@ -21,6 +21,7 @@ "matomo", "metabase", "mkdocs", + 'mycompany' "nocheck", "Nouislider", "overidden", From b7a7fd2d8c3f812245859a6d61a0b60f3cee703d Mon Sep 17 00:00:00 2001 From: chrismclarke Date: Tue, 26 Mar 2024 22:09:51 -0700 Subject: [PATCH 6/6] chore: lint fixes --- cspell.config.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cspell.config.yml b/cspell.config.yml index 202631cbb..e82ef1081 100644 --- a/cspell.config.yml +++ b/cspell.config.yml @@ -21,7 +21,7 @@ "matomo", "metabase", "mkdocs", - 'mycompany' + "mycompany", "nocheck", "Nouislider", "overidden",