TWAQI — Taiwan air quality
Taiwan air-quality app for iPhone, iPad, Apple Watch, Apple Vision Pro and Android, with Home Screen widgets, push alerts and station cams. Website, privacy policy and terms: taiwanair.wahthefox.com. Contact: [email protected].
Download
Get it on Google Play
Screenshots
iOS
Android
Apple Watch
Apple Vision Pro
Repository layout
Two platforms in one repository (FOX-89):
| Folder | What |
|---|
ios/ | The Apple app: TWAQI.xcworkspace / TWAQI.xcodeproj, the targets (TWAQI, TWAQIWidget, TWAQIWatch, TWAQIWatchWidget, TWAQIVision, TWAQITests, TWAQIUITests), Podfile, fastlane/ and .swiftlint.yml |
android/ | The Android app (Kotlin + Jetpack Compose, package com.kfpun.twaqi) and its Wear OS app; see android/README.md |
| root | Shared: .github/, .githooks/, docs/, tools/, assets/, services/, web/, workers/, Firebase Hosting (firebase.json, .firebaserc) |
Development (iOS)
# Clone this repo
$ git clone [email protected]:7kfpun/SwiftUI-TWAQI.git
# Go inside the iOS project and install pod dependencies
$ cd SwiftUI-TWAQI/ios && pod install
# Copy example config
$ cp TWAQI/Config/example.xcconfig TWAQI/Config/debug.xcconfig
# Get a Google Maps API key, https://developers.google.com/maps/documentation/ios-sdk/get-api-key, and update the key `GMSServicesApiKey` in the debug.xcconfig file
$ open TWAQI/Config/debug.xcconfig
# Create a Firebase project and download the config file, GoogleService-Info.plist, to the folder, https://firebase.google.com/docs/ios/setup
$ cp ~/GoogleService-Info.plist TWAQI/GoogleService-Info.plist
# Directus: set DirectusFeedbackToken (and optionally DirectusCooperateToken) in debug.xcconfig, and PushApiUrl for push — see the comments in example.xcconfig
# Open Xcode and run with Command (⌘)-R
$ open TWAQI.xcworkspace
The commands above run in ios/. ios/TWAQI/Config/debug.xcconfig, release.xcconfig and ios/TWAQI/GoogleService-Info.plist are gitignored; they hold real keys. So is ios/fastlane/.env.
Targets: TWAQI (iPhone/iPad, iOS 15), TWAQIWidget, TWAQIWatch + TWAQIWatchWidget, TWAQIVision (visionOS), all under ios/. Cloudflare Workers live under workers/<name>/, the Cloud Run read API under services/twaqi-api/.
Development (Android)
Needs JDK 17 and the Android command-line tools (platform 36). Details, config and release steps: android/README.md.
export JAVA_HOME=$(brew --prefix openjdk@17)/libexec/openjdk.jdk/Contents/Home
export ANDROID_HOME=$(brew --prefix)/share/android-commandlinetools
cd android
# Optional: real keys. A clean checkout builds with secrets.example.properties alone.
cp secrets.example.properties secrets.properties # then fill in API_DOMAIN, MAPS_API_KEY, ...
./gradlew ktlintCheck lint test assembleDebug
android/secrets.properties, android/app/google-services.json and android/keystore.properties are gitignored.
Services
| What | Where |
|---|
| Air-quality readings | MOENV open data, pulled into MySQL (Cloud SQL) every 20 min by the AWS Lambda (7kfpun/lambda-serverless). The app reads it from the API_DOMAIN endpoints in the xcconfig: the Lambda's API, or the same /v1 API on the webcam host (a route on workers/twaqi-workers → Cloud Run services/twaqi-api, FOX-82), byte-for-byte the same responses |
| In-app feedback (Help → Feedback / Contact us) | Directus (DirectusUrl), collection twaqi_feedback, with the app's static token (DirectusFeedbackToken) |
| 空品區 AQI forecast | Directus twaqi_aqi_forecast, filled hourly from MOENV AQF_P_01 by workers/twaqi-workers; the app only reads it |
| Business partner form (Help → Interested to be our Business Partner?) | Directus collection twaqi_cooperate, create-only with DirectusCooperateToken, or DirectusFeedbackToken when that is empty; soft delete via archived |
| Station webcams | R2 bucket twaqi-station-cams behind the webcam host (its custom domain), synced every 10 min by workers/twaqi-workers |
| Weather on the station page (FOX-11) | Central Weather Administration (CWA) open data (F-C0032-001 county forecast, O-A0003-001 observations), written hourly by workers/twaqi-workers to weather/latest.json in the same bucket, read from the webcam host. The CWA key stays in the Worker |
| Push alerts | Firebase Cloud Messaging, settings in Directus (see below) |
| Crash reporting / analytics | Firebase Crashlytics + Analytics only (Swift Package Manager) |
| Website, privacy policy, terms | web/ on Firebase Hosting at (site ); 301s there. Cutover runbook: |
Station webcams
- Latest frame:
<webcam host>/stations/{siteId}.jpg (plus manifest.json, which maps each siteId to its name, location and latest hourKey).
- Hourly history:
stations/{siteId}/{yyyy-MM-dd}/{HH}.jpg — one frame per site per clock hour, yyyy-MM-dd and HH in Taiwan time (Asia/Taipei, UTC+8). The station screen's scrubber reads the last 24 of these.
- R2 keeps a rolling 24 h of hourly frames. A missing hour is a plain 404; the app treats it as missing, not as a failure.
siteId is the MOENV image site id (001), not a TWAQI station id; the app matches cams to stations by name, then by distance.- On device, fetched frames and hourly frames are cached for offline use and purged after a week, along with the other offline caches.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
