Merge pull request #959 from ably/example-app-distribution-documentation

Example App Distribution documentation

CONTRIBUTING.md

@@ -115,6 +115,75 @@ Details for the Sonatype identity to be used to publish to our Ably's `com.ably`
 - `OSSRH_USERNAME`: The Sonatype user.
 - `OSSRH_PASSWORD`: The password for the Sonatype user.
 
+## Secrets Required to Distribute the Example Apps
+
+The primary (Kotlin, not Java) example apps
+([Publishing](publishing-example-app/)
+and
+[Subscribing](subscribing-example-app/))
+were initially developed with a focus on them being useful to developers working on this codebase to provide them with a test harness for quick, manual, local/desk-bound testing as they worked on features and bug fixes.
+These example apps, however, also grew to attain functionality that helps us and the wider Ably team do 'in the field' manual testing more akin to QA (Quality Assurance) testing.
+
+In order to allow these example apps to be installed OTA (Over-The-Air) onto the Android devices of manual/QA testers where there is no development environment (e.g. Android Studio) attached we have configured their Gradle projects to support [Firebase App Distribution](https://firebase.google.com/docs/app-distribution).
+
+How these secrets are used by the Gradle build runtime can be best observed by inspecting
+[the `publish-example-apps` workflow file](.github/workflows/publish-example-apps.yml).
+
+**Partially Supported:**
+We have only configured this for the Publishing Example project so far.
+We will add it to the Subscribing Example App project when we work on
+https://github.com/ably/ably-asset-tracking-android/issues/957.
+
+### Android App Signing Key
+
+The secrets used to configure the Android app signing configuration are called:
+
+| Secret Name | Gradle Build Input Mechanism | Description |
+| ----------- | ---------------------------- | ----------- |
+| `AAT_SDK_EXAMPLE_APPS_ANDROID_SIGNING_JKS_FILE_BASE64` | Hydrated (decoded from base64) to file at `publishing-example-app/signing.jks` | This is a Java KeyStore file and can be created using Android Studio using the instructions [here](https://developer.android.com/studio/publish/app-signing#generate-key). Configures [the `storeFile` property](https://developer.android.com/reference/tools/gradle-api/4.2/com/android/build/api/dsl/SigningConfig#storeFile:java.io.File). |
+| `AAT_SDK_EXAMPLE_APPS_ANDROID_SIGNING_KEY_ALIAS` | Property with the same name. | Configures [the `keyAlias` property](https://developer.android.com/reference/tools/gradle-api/4.2/com/android/build/api/dsl/SigningConfig#keyAlias:kotlin.String). |
+| `AAT_SDK_EXAMPLE_APPS_ANDROID_SIGNING_KEY_PASSWORD` | Property with the same name. | Configures [the `keyPassword` property](https://developer.android.com/reference/tools/gradle-api/4.2/com/android/build/api/dsl/SigningConfig#keyPassword:kotlin.String). |
+| `AAT_SDK_EXAMPLE_APPS_ANDROID_SIGNING_STORE_PASSWORD` | Property with the same name. | Configures [the `storePassword` property](https://developer.android.com/reference/tools/gradle-api/4.2/com/android/build/api/dsl/SigningConfig#storePassword:kotlin.String). |
+
+### Google Services
+
+This file is required by the
+[Google Services Gradle Plugin](https://developers.google.com/android/guides/google-services-plugin)
+to (optionally) supply the Gradle build runtime with the information it requires to:
+
+- Build [Firebase Crashlytics](https://firebase.google.com/products/crashlytics) support into the example app runtime
+- Build [Firebase App Distribution](https://firebase.google.com/docs/app-distribution) support into the Gradle build runtime
+
+The secret, for the Publishing Example App, is called `PUBLISHING_EXAMPLE_APP_GOOGLE_SERVICES_JSON`.
+
+### Google Service Account
+
+A
+[Service Account](https://cloud.google.com/iam/docs/service-accounts)
+is required to upload example apps to the Firebase App Distribution service and contains the secret information required by the Gradle build runtime to authorise with that service using
+[the `appDistributionUploadRelease` task](https://firebase.google.com/docs/app-distribution/android/distribute-gradle#step_4_distribute_your_app_to_testers)
+that is provided by
+[the Firebase App Distribution Gradle plugin](https://maven.google.com/web/index.html?q=firebase-appdistribution-gradle).
+
+The secret is called `ASSET_TRACKING_SDKS_GSERVICEACCOUNT_PRIVATE_KEY_JSON`.
+
+Creating the Service Account and then providing it the necessary roles and permissions can be done in a number of ways but for our initial setup and testing of this capability was achieved using Google Cloud's
+[IAM and admin Console (Web UI)](https://console.cloud.google.com/iam-admin/).
+The
+[Policy troubleshooter tool](https://cloud.google.com/policy-intelligence/docs/troubleshoot-access)
+therein is highly recommended as it was helpful to work out which roles needed to be given to this account in order for it to succeed in authorising with Firebase App Distribution.
+
+For the `firebaseappdistro.releases.update` permission for the Firebase project resource we found that the following roles were required for this service account to allow the Gradle task to succeed in uploading to Firebase App Distribution:
+
+- Editor
+- Firebase App Distribution Admin
+- Owner
+
+**Caveat**: The initial author of this guidance is not an expert in Firebase or IAM. Your mileage may vary. Stuff changes. It is strongly suggested to read Google Docs yourself for canonical guidance, or consult an expert.
+
+**OpenID Connect (OIDC):** We should be using this, but we're not yet, but will once we work on
+https://github.com/ably/ably-asset-tracking-android/issues/958.
+
 ## Release Process
 
 Releases should always be made through a release pull request (PR), which needs to bump the version number and add to the [change log](CHANGELOG.md).

README.md

@@ -50,6 +50,10 @@ MAPBOX_ACCESS_TOKEN=create_token_with_all_public_scopes
 GOOGLE_MAPS_API_KEY=create_api_key_with_geolocation_maps_sdk
 ```
 
+Our Gradle build configuration also has support for uploading example apps to Firebase App Distribution with Crashlytics support - see
+[`CONTRIBUTING.md`: Secrets Required to Distribute the Example Apps](CONTRIBUTING.md#secrets-required-to-distribute-the-example-apps)
+for more detail on this.
+
 ## Usage
 
 Please see our [Upgrade / Migration Guide](UPDATING.md) for notes on changes you need to make to your code to update the Ably Asset Tracking SDKs.