AI Usage Dashboard Docs

AI Usage Dashboard 모바일 위젯 싱크 설치/세팅 가이드

이 문서는 데스크탑 AI Usage Dashboard에서 수집한 사용량 snapshot을 Android 위젯으로 동기화하는 방법을 설명합니다.

핵심 구조: 데스크탑 앱이 provider 사용량을 새로고침 → Cloudflare Relay에 안전한 snapshot 업로드 → 모바일 앱/위젯이 sync URL로 snapshot을 가져옴 → Android는 FCM wake signal + WorkManager polling으로 자동 갱신합니다.

1. 자동 갱신이 되는 조건

정리하면, PC 서버/데스크탑 앱이 켜져 있고 refresh가 계속 돌면 모바일도 계속 따라옵니다. 단, FCM/Android 배터리 정책 때문에 완전한 실시간 보장은 아니며, polling fallback으로 eventual sync를 보장합니다.

2. 필요한 것

데스크탑/개발 환경

Android 기기

3. 저장소 준비

git clone <repository-url>
cd ai-usage-dashboard
npm install
npm run typecheck
cargo check --manifest-path apps/desktop/src-tauri/Cargo.toml

개발 모드 실행은 실제 사용자 HOME을 명시하는 것이 안전합니다. provider credential은 보통 실제 사용자 홈 디렉터리에 있기 때문입니다.

HOME="$HOME" npm run dev:tauri

macOS에서 Hermes/자동화 환경 안에서 실행한다면 다음처럼 실제 계정 HOME을 명시하세요.

HOME=/Users/<you> npm run dev:tauri

4. Firebase Android 앱 설정

  1. Firebase Console에서 project를 만듭니다.
  2. Android app을 추가합니다.
  3. package name은 앱의 namespace와 같아야 합니다.
com.aiusagedashboard.widget
  1. Firebase에서 google-services.json을 다운로드합니다.
  2. 아래 위치에 넣습니다.
apps/android/app/google-services.json

주의:

5. Cloudflare Relay 설정

Cloudflare relay는 데스크탑이 업로드한 snapshot을 모바일이 가져갈 수 있도록 보관합니다.

5.1 Worker 배포

npm run deploy:relay:cf

배포 후 Worker base URL을 기록합니다.

https://<your-worker>.<your-account>.workers.dev

5.2 FCM service account secrets 등록

Firebase Console에서 service account JSON을 발급한 뒤, 값 자체를 코드나 문서에 넣지 말고 Cloudflare Worker secret으로만 등록합니다.

필요한 secret:

FCM_PROJECT_ID
FCM_CLIENT_EMAIL
FCM_PRIVATE_KEY

예시:

npx wrangler secret put FCM_PROJECT_ID
npx wrangler secret put FCM_CLIENT_EMAIL
npx wrangler secret put FCM_PRIVATE_KEY

주의:

6. Android APK 빌드/설치

npm run build:android

APK 위치:

apps/android/app/build/outputs/apk/debug/app-debug.apk

ADB 설치:

adb install -r apps/android/app/build/outputs/apk/debug/app-debug.apk

필요하면 downgrade 허용:

adb install -r -d apps/android/app/build/outputs/apk/debug/app-debug.apk

7. 데스크탑 앱에서 sync URL 만들기

  1. 데스크탑 앱을 엽니다.
  2. provider 연결 상태를 확인합니다.
  3. Settings로 이동합니다.
  4. System 섹션으로 이동합니다.
  5. Android widget sync를 켭니다.
  6. Relay URL에 Worker base URL을 입력합니다.
https://<your-worker>.<your-account>.workers.dev
  1. 앱이 표시하는 전체 sync URL을 복사합니다.

형태는 다음과 같습니다.

https://<your-worker>.<your-account>.workers.dev/v1/snapshots/<pairId>?token=<syncToken>

중요:

8. Android 앱과 위젯 연결

  1. Android 앱을 실행합니다.
  2. 데스크탑 앱에서 복사한 전체 sync URL을 입력합니다.
  3. Sync Widget을 누릅니다.
  4. 성공 메시지가 나오면 홈 화면에 위젯을 추가합니다.
  5. 이후부터는 다음 경로로 자동 갱신됩니다.
    • Android 앱 open 시 자동 sync
    • WorkManager periodic sync
    • 위젯 update 이벤트
    • Cloudflare relay의 FCM wake signal

9. 동작 방식 상세

Desktop app
  refreshes provider usage
  builds sanitized snapshot
  PUT /v1/snapshots/:pairId Authorization: Bearer <syncToken>

Cloudflare relay
  stores latest sanitized snapshot
  sends wake-only FCM message when snapshot etag changes

Android app/widget
  receives wake signal
  enqueues WidgetSyncWorker one-shot
  GET /v1/snapshots/:pairId?token=<syncToken>
  stores snapshot in SharedPreferences
  refreshes home-screen widget

FCM payload에는 provider 사용량, sync URL, sync token이 들어가지 않습니다. push는 단지 “새 snapshot이 있으니 fetch해라”라는 wake signal입니다.

10. 문제 해결

위젯이 갱신되지 않음

데스크탑 앱에서 provider가 연결 필요로 보임

HOME=/Users/<you> npm run dev:tauri

FCM push가 안 옴

Cloudflare Worker는 응답하는데 snapshot이 없음

처음에는 데스크탑 앱이 한 번 provider refresh와 snapshot upload를 해야 합니다. 데스크탑 앱에서 Android widget sync를 켠 뒤 provider refresh를 실행하세요.

11. 보안 체크리스트

12. 현재 한계