Spezi

Kotlin & Android Version of the Stanford Spezi Framework

An Ecosystem of Modules

Spezi is a collection of modules that can be used to build Android applications

Modules

• Core & Foundation: Shared building blocks and utilities used across the framework (core, foundation, core-coroutines, core-lifecycle, core-logging, core-time, core-viewmodel)
• UI & Design System: Cohesive user interface and user experience components (ui, ui-theme, ui-account, ui-markdown, ui-personalinfo, ui-validation)
• Account: Account management components, with a Firebase-backed implementation (account, account-firebase)
• Health: Health Connect data integration, plus FHIR Questionnaire rendering (health, questionnaire)
• Contact: Contact screens (contact)
• Storage: Local object/key-value storage, plus Credential storage (storage-local, storage-credential)
• Testing: Shared test infrastructure (testing-core, testing-ui, testing-screenshot, testing-concurrency)

A runnable demonstration of these modules is available in the sample-app.

Getting Started

Prerequisites

• Android Studio (latest stable)
• JDK 17
• An Android device or emulator running API 31 (Android 12) or newer

Run the sample app

The sample-app module is the quickest way to see the framework in action.

git clone https://github.com/StanfordSpezi/SpeziKt.git
cd SpeziKt
./gradlew :sample-app:installDebug   # build and install on a connected device/emulator

Or open the project in Android Studio, select the sample-app run configuration, and press Run. To build and test everything from the command line:

./gradlew build

Use a module in your app

Spezi is a multi-module Gradle project. Add the modules you need as project dependencies and apply the Spezi convention plugins in your module's build.gradle.kts:

plugins {
    alias(libs.plugins.spezi.application)
    alias(libs.plugins.spezi.compose)
}

dependencies {
    implementation(project(":core"))
    implementation(project(":ui"))
    implementation(project(":account"))
}

Then declare the modules you want in a Configuration on your Application. Spezi builds the dependency graph at startup and wires everything together:

class MyApplication : Application(), SpeziApplication {
    override val configuration = Configuration {
        // register the modules your app uses
    }
}

See each module's README (linked above) for its specific API and usage, and the core module for how Module, Standard, and Configuration fit together.

Continuous Integration and Delivery Setup

Google Play Internal Deployment

First, create a Google Cloud Services Account and corresponding JSON secrets key in accordance to the fastlane supply documentation. Store the JSON representation of the key in a SERVICE_ACCOUNT_JSON_KEY secret available to the GitHub action.

Follow along the Set up your Google APIs console documentation to create a OAuth client ID. Store secrets.xml representation of the key in a SECRETS_XML secret available to the GitHub action.

This is the secrets.xml representation of the key:

<?xml version="1.0" encoding="utf-8"?>
<resources>
  <string name="serverClientId" translatable="false">replace-with-actual-id</string>
</resources>

In Firebase, the provider Google must also be added in the project in the Authentication menu item in the Login method tab.

It is recommended to sign your APK before uploading it to the Google Play store. Setup your signing setup as detailed in the Sign your app documentation.

Create a base64 representation of your keystore (base64 -i ./filetokeystore/keystore.jks) and save it in the KEY_STORE secret available to the GitHub action. Save the keystore password and key password in the KEY_PASSWORD secret and save the key alias in the KEY_ALIAS secret, both available to the GitHub action.

Contributing

Contributions to this project are welcome. Please make sure to read the contribution guidelines and the contributor covenant code of conduct first.

License

This project is licensed under the MIT License. See Licenses for more information.