stanfordspezi / spezitemplateapplication

Template application demonstrating the usage of the Stanford Spezi framework.

Spezi Template Application

This repository contains the Spezi Template Application. It demonstrates using the Spezi ecosystem and builds on top of the Stanford Biodesign Digital Health Template Application.

Note

Do you want to try out the Spezi Template Application? You can download it to your iOS device using TestFlight!

Application Content

The following screenshots show a wide variety of features based on Spezi Modules that are part of the Spezi Template Application.

Welcome View	Interesting Modules	Consent Signature

HealthKit Access	Granular HealthKit Share Control	Schedule Tasks

Trigger Local Notifications	Display Questionnaires	Keep Track of Tasks

Contact Information	License Information	Mock Web Service Requests

Note

You can find all the used Spezi Modules in the Stanford Spezi GitHub Organization.

The DocC documentation of the Spezi Template Application contains information on how to use the application as the basis for your Spezi-based application, run the application, and modify the application.

Contributing

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

This project is based on ContinuousDelivery Example by Paul Schmiedmayer and the Stanford Biodesign Digital Health Template Application provided using the MIT license.

License

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

spezitemplateapplication's Issues

Create a script for renaming the project

Use Case

Creating a new project from the template application.

Problem

Renaming the template application manually after starting a new project is cumbersome and time consuming.

Solution

We should create a script that will replace "TemplateApplication" in the folder names, file names, and code of the template application with the name of the user's project automatically.

Alternatives considered

https://github.com/yonaskolb/XcodeGen

Additional context

No response

Code of Conduct

• I agree to follow this project's Code of Conduct and Contributing Guidelines

Reset user context on account logout

Description

The template app currently enforces to be logged into a user account. Once you log out from the account, a sheet pops up requiring you to sign back in, before you can continue to use the app.
While this works as expected, the Schedule is not paused. For example, the app continues to deliver notifications to complete the social support questionnaire.

Reproduction

1. Onboard the app.
2. Logout from your account.
3. Wait till 8am to get a schedule notification delivered.

Expected behavior

It would be expected that the app clears all currently queued scheduled notifications and only reschedule them once the user signs back in. This (probably) requires an additional API surface in SpeziScheduler module and some additional account related handling in the ScheduleView.

Additional context

No response

Code of Conduct

• I agree to follow this project's Code of Conduct and Contributing Guidelines

Improve UI Testing Setup

Problem

Some UI tests in the application need to go through the onboarding flow to test the functionality in the app. This is taking a long time and might not be needed every time.

Solution

I would suggest the following options:

• We could add code to the template app that executes, e.g., notifications permissions and HealthKit. The UI test then handles the popups and other permissions screens once the application is launched, skipping the onboarding flow.
• Once we have addressed #27, we could add arguments to the onboarding feature flag to only show specific onboarding views to more quickly move through the onboarding flow.

Additional context

No response

Code of Conduct

• I agree to follow this project's Code of Conduct and Contributing Guidelines

Complete Concurrency Checking

Problem

With Swift 6 approaching in a few months and nightly builds already being available we should ensure that all our packages are working well with all Swift concurrency checks.

Solution

Enable Enable strict concurrency checking.

The corresponding PR should fix all related warnings when enabling strict concurrency checking.

The relevant package updates in StanfordSpezi/.github#49 need to be addressed first.

Additional context

We should consider adding SWIFT_TREAT_WARNINGS_AS_ERRORS = YES to our general workflows to enforce that all warnings are flagged as errors during our CI setup.

Code of Conduct

• I agree to follow this project's Code of Conduct and Contributing Guidelines

Add Xcode Preview to All Views

Problem

Currently some views in the template application crash due to missing environment objects and some views do not provide any previews for the views.

Solution

Add the corresponding environment objects to the views and children by using a mechanism like proposed in StanfordSpezi/Spezi#63.

In addition, we should use the new Preview macro as introduced with Xcode 15/Swift 5.9.

Additional context

This issue requires a mechanism as described in StanfordSpezi/Spezi#63 to make the injection of modules easy when working with Xcode previews.
Feel free to discuss the implications and ideas for APIs in the StanfordSpezi/Spezi repository and help us to address this issue.

We would encourage anyone who wants to address this PR to first watch the WWDC23 - Build programmatic UI with Xcode Previews session to learn more about previews and the new macros.

Code of Conduct

• I agree to follow this project's Code of Conduct and Contributing Guidelines

Internal change: Re-add CodeQL job as soon as CodeQL supports Swift 5.9

Problem

At the moment, the CodeQL analysis engine for GitHub code scanning doesn't support Swift 5.9: github/roadmap#800
This presents a challenge to our Spezi use case, as we are using Swift 5.9 features.

Solution

For now, #42 removes the CodeQL job.
As soon as CodeQL supports Swift 5.9, re-add the job to the pipeline.

Additional context

Issue from CodeQL: github/roadmap#800

Code of Conduct

• I agree to follow this project's Code of Conduct and Contributing Guidelines

Use String Catalogues

Problem

The current String.localized files are challenging to keep up to date and do not scale well if we add support for multiple languages.

Solution

Apple introduced and embedded String Catalogs in Xcode 15 and with Swift 5.9. The following WWDC session and documentation provides a good overview:

• https://developer.apple.com/videos/play/wwdc2023/10155
• https://developer.apple.com/documentation/Xcode/localizing-and-varying-text-with-a-string-catalog

The seem to be supported for Swift Packages: https://developer.apple.com/forums/thread/731941

Additional context

This issue is part of the Use String Catalogues focus area.

Code of Conduct

• I agree to follow this project's Code of Conduct and Contributing Guidelines

Use Codable for Firestore

Problem

Currently, the SpeziTemplateApplication has a short code sample where it uploads data to Firestore. In this example we manually map our Model data to a [String: Any] dictionary and pass it to firebase. This is actively discouraged.

Solution

Firebase recommends using Swift's Codable to encode and decode Model data to and from Firestore. For more information see their documentation.

Additional context

This issue specifically talks about the following lines of code:

SpeziTemplateApplication/TemplateApplication/TemplateApplicationStandard.swift

Lines 65 to 75 in 092d431

	let data: [String: Any] = [
	"id": details.userId,
	"firstName": details.name?.givenName ?? "",
	"lastName": details.name?.familyName ?? ""
	]
	do {
	try await userDocumentReference.setData(data)
	} catch {
	logger.error("Could not update user information in Firebase: \(error)")
	}

Code of Conduct

• I agree to follow this project's Code of Conduct and Contributing Guidelines

Documentation Improvements

Problem

The Template Application should include more structured documentation that takes inspiration from the README but restructures and decomposes the setup into smaller elements.

Solution

This includes:

• Setting up your development environment
  • This includes installing Xcode, Swift, swiftlint, REUSE tool, and more
  • We should automate as much as possible, e.g., reusing elements of https://github.com/StanfordBDHG/ContinousIntegration/blob/main/install.sh.
  • This functionality can be put in the Spezi Template Application, but I am even leaning toward putting it into our Spezi documentation as a "Get Ready with Contributing" or "Developing with Spezi" guide.
  • This documentation might change with each Xcode release, so we should ensure that we use screenshots that are easily replaceable and point to Apple and other documentation as much as possible.
  • Explain how these checks & automated are performed on each PR and why this is beneficial.
• Setup your local Firebase Emulator Environment
  • This includes installing everything and getting started with using the emulator. We should explain the use cases of not using a QA or production system for development, make the setup as easy as possible using a setup script (e.g., reusing elements of https://github.com/StanfordBDHG/ContinousIntegration/blob/main/install.sh).
  • The tutorial should include the importance of maintaining, testing, and updating security rules. We should ensure that we point to the Firebase documentation, if possible, to ensure that any changes in their system don't require us to rewrite the tutorial.
  • We should be mindful that a lot of this documentation should move to the Spezi Firebase Spezi Module and should be linked here.
• Setup your QA or production Firebase environment.
  • Point to the right resources to set up your Firebase environment, and add the right Firebase products and configuration. We should ensure that this documentation is easily extendable when and if we add additional functionality in the Template App.
  • It should include a section on how to change the two main configuration files (.firebaserc and the BUNDLE_ID and PROJECT_ID in the GoogleService-Info.plist)
  • How to administer a services account, provide the minimal scope of permissions (in our case, only write access to the security rules for storage and database), and enable the automated deployment using GitHub Actions.
  • A lot of this documentation should probably move to the Spezi Firebase Swift Package as we want to move the Template Application away from Firebase.
• Setup continuous integration for the template application and TestFlight/AppStore Deployment
  • Explain the need for the different secrets and where and how they are used (see the ContinuousDelivery Example by Paul Schmiedmayer and the Stanford Biodesign Digital Health Template Application as references).
  • Link to Fastlane documentation and additional context about the setup in this repo.
  • Explain how to setup Sign in With Apple for the project. Most of this should probably move to Spezi Firebase and the Account Module in there.
  • Explain the use of GitHub Actions to deploy the application and how this is embedded in the configuration of the application
  • Link to Apple resources on how to change the TestFlight setup, add testers, create a public link, and eventually push the app to the App Store
• How the application is structured and how Spezi is used
  • Explain the usage of the different Spezi Modules in the application, link to the corresponding Spezi and Spezi module docs
  • Explain how to extend the setup in different directions
  • Explain how to use components and modules in your setup and lead off with a suggestion to contribute back to the Spezi ecosystem.

Additional context

It would be great to get community input on these issues, which students and developers are struggling with the most. Please use this issue to discuss the focus area.

Nevertheless, we must ensure we don't reinvent the wheel and set up. We should extensively point to Apple documentation (e.g., https://developer.apple.com/tutorials/app-dev-training/) or Firebase Documentation.
There is no need to re-explain Swift or SwiftUI concepts; we should point to web pages like https://www.hackingwithswift.com/100/swiftui and https://docs.swift.org/swift-book/documentation/the-swift-programming-language/guidedtour/.

Code of Conduct

• I agree to follow this project's Code of Conduct and Contributing Guidelines

Logout Button Allows to Skip Account Setup

Description

The AccountSetup can fundamentally display two different states

• No account logged in
• Account logged in

In the second state, the UI displays an logout button (e.g. allowing you to change your account again). This can be either reached when navigating back from the "HealthKit Access" view or when uninstalling and reinstalling the app.
The problem is that when pressing the Logout button the view will jump to the next onboarding step allowing to skip Account onboarding.

Reproduction

1. Go throng the onboarding steps till you reach Account onbaording
2. Sign into your account
3. Once arriving at the "HealthKit Access" view navigate Back.
4. Press the Logout button (this will trigger the will change of the Account instance where signedIn is still set to true, resulting in our onReceive handler getting called and navigating us to the next onboarding step).
5. Continue with HealthKit Access
6. You now finished the onboarding flow and entered the App without being signed into an Account

Expected behavior

I would expect the AccountSetup view to just re-render when pressing the Logout button, requiring me to create a new account or sign into a different account.
More specifically, as a programmer, I would expect that once the user completed the onboarding flow, I can be pretty sure that they are signed into an account.

Additional context

A possible workaround is to set signedIn to false before calling the Logout button action.

Button("Logout", role: .destructive) {
    account.signedIn = false // workaround

    try? Auth.auth().signOut()
}

I haven't gone into the specifics on how SpeziAccount/SpeziFirebase specifics work. It may be sensible to provide a first party API to handle sign out. Or is there already?

Code of Conduct

• I agree to follow this project's Code of Conduct and Contributing Guidelines

Schedule View doesn't update Tasks when opening through notification.

Description

In the current template, one gets notified if the social support questionnaire is ready to be filled out again (daily basis on 8am). However, if you open the App by clicking on the notification (and you completed the questionnaire on the previous day), the questionnaire still shows as completed. Only if you navigate away (e.g. Contacts view) and back, then the Schedule view refreshes and shows the questionnaire as available.

Reproduction

• Open the template app and complete the questionnaire
• Get notified about the questionnaire being available again
• Tap the notification and be presented with a stale schedule view

Expected behavior

The schedule view should update upon reopening the app.

Additional context

I haven't further investigated the issue and its core cause. Upon further investigation it might make sense to move this issue to SpeziScheduler.

Code of Conduct

• I agree to follow this project's Code of Conduct and Contributing Guidelines

Local Mock Mode & Cloud Storage Independence

Problem

The current version of the Spezi Template Application requires the Firebase emulator to be up and running to use and try out the template application. This is a significant hurdle for developers to get started, requires a large dependency to be bundled with the template application, and limits our ability to easily use the application for small tests where a full cloud infrastructure might not be needed.

Solution

The template application should either include a local mock mode or completely remove the dependency on Firebase in its default configuration.
The mock mode should be the default setup when the application is run, and communicating with Firebase in the debug mode should be controlled by a feature flag.

If we decide that the Firebase module should be completely removed, we should add a DocC article on connecting the template application to a cloud provider and use Firebase as an example or provide a fork of the template application that demonstrates a variant of the application using Firebase.

Code of Conduct

• I agree to follow this project's Code of Conduct and Contributing Guidelines

Add an Open-Source Contributions Screen

Problem

The application currently does not provide any way to see all open-source tools used within the app, nor does it give access to all licenses used.

Solution

Add a screen to the application that highlights all open-source tools and dependencies used in the application, including their licenses and correct attributions.

Code of Conduct

• I agree to follow this project's Code of Conduct and Contributing Guidelines

Template Application always uses English localization

Description

The template application always uses the English localization, even if modules have localization for other languages. This is likely because the template application only has an English localization and iOS does not allow mixed localization by default. Mixed localization can be set using CFBundleAllowMixedLocalizations.

See a related discussion here.

Reproduction

Set the language to "German" in either the Settings pane of the simulator, or in the Scheme Editor. This should result in modules which have German localization using German strings within the template application. However, the template application still uses English strings.

Expected behavior

We expect that if strings are available in a user's preferred language, they will be displayed. By default, iOS will not allow mixed localizations. The ideal solution is to add localizations for all languages to the template app that are supported by our modules. However, this is likely too much to expect developers to update when creating their own apps from the template. Alternatively, we can set CFBundleAllowMixedLocalizations to YES which will allow mixed localization by default. This would allow strings to be shown in the user's preferred language if available. As noted in the article linked above, there is a possible downside to this if individually localized strings are interpolated into each other, but this does not seem to an issue that will occur with our current application. The benefit of users being able to see at least part of the interface in their preferred language is likely to outweigh the downsides for most use cases.

Additional context

No response

Code of Conduct

• I agree to follow this project's Code of Conduct and Contributing Guidelines

Skip the HealthKit Permissions View if the Permissions Are Already Provided

Problem

This issue is related to StanfordSpezi/SpeziHealthKit#6: It would be ideal of the HealthKit onboarding step is skipped when the permission for the current HealthKit types has already been provided.

Solution

Once StanfordSpezi/SpeziHealthKit#6 is closed, we should add a conditional statement to the onboarding flow of the previous onbarodhing step to conditionally show the HealthKit onboarding flow in case the permission have already been provided.

Additional context

Please reference to StanfordSpezi/SpeziHealthKit#6 about more information about the required changes in the HealthKit module.
We are happy to provide guidance and help if you want to work on this issue. Feel free to use the comment section under this issue to discuss your possible approach and how you plan to address the issue.

Code of Conduct

• I agree to follow this project's Code of Conduct and Contributing Guidelines

Bug report: HealthKit Sample Upload Before Firebase Login

Description

When closing the app entirely (not running in the background) and opening it again, some HK samples can get lost as they are never transferred to Firebase. From reading the log messages (error message: Could not store HealthKit Sample: Error Domain=Standard.StandardError Code = 0). I believe that this is due to the app trying to push data to Firebase before the app is authenticated with Firebase.

Reproduction

Closing the app entirely (in the simulator and a real device), not just pressing the home button (or the equivalent for the newer iPhones), creating a new HealthKit sample (e.g., manually adding it in the Health App) and then re-opening the template application causes the error. The error message can be seen when the console entries are logged or through observing the Firebase backend.

Expected behavior

The authentication should happen first and only after the app is correctly authenticated, a sample transfer should happen and no samples should be lost.

Additional context

No response

Code of Conduct

• I agree to follow this project's Code of Conduct and Contributing Guidelines

Update Template App to Spezi 0.7.0

Remove Mock Web Service

Problem

Currently, we maintain a Mock Web Service integration in the case you run your project without Firebase. However, this doesn't really help to demo any functionality and just increases the code complexity making it harder to start out with the template application.

Solution

Remove the MockWebService integration and remove the dependency.

Additional context

No response

Code of Conduct

• I agree to follow this project's Code of Conduct and Contributing Guidelines

Move the License Information Logic And Views Into a Separate Spezi License Swift Package

Problem

A lot of the code related to license information display of dependencies create by @NikolaiMadlener (thank you!) is quite reusable and might not change too much in the development of an own Spezi Application. This could move out of the Spezi Template Application into an own Spezi module.

Solution

Create an own repo and host the code there in a more reusable fashion and then import this package in the Spezi Template Application.

Additional context

No response

Code of Conduct

• I agree to follow this project's Code of Conduct and Contributing Guidelines