diff --git a/cspell.config.yml b/cspell.config.yml index a837b998c4..e82ef1081d 100644 --- a/cspell.config.yml +++ b/cspell.config.yml @@ -21,6 +21,7 @@ "matomo", "metabase", "mkdocs", + "mycompany", "nocheck", "Nouislider", "overidden", diff --git a/documentation/docs/developers/android-assets.md b/documentation/docs/developers/android-assets.md index ee7cd42500..389efce745 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,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 ``` diff --git a/documentation/docs/developers/deployments.md b/documentation/docs/developers/deployments.md index 6530b0f8ca..a5edab7e06 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,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 diff --git a/documentation/docs/developers/in-app-updates.md b/documentation/docs/developers/in-app-updates.md index 3275cc8e10..99e3fdbe01 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) @@ -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) diff --git a/documentation/docs/developers/quickstart.md b/documentation/docs/developers/quickstart.md index 9fd201284a..364f88def8 100644 --- a/documentation/docs/developers/quickstart.md +++ b/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.