Google Fit Integration Guide
This guide documents the Google Fit REST API integration in the PPP wellness module, covering OAuth2 setup, data sync, and infrastructure configuration.
1. Architecture Overview
What Google Fit Is Used For
The PPP platform uses Google Fit for read-only wellness data synchronization:
- Activity data -- steps, calories burned, active minutes
- Sleep data -- sleep sessions and stages
- Heart rate -- resting and continuous heart rate
- Body metrics -- weight, BMI
- Blood oxygen -- SpO2 readings
Data Flow
User clicks "Connect Google Fit"
|
v
Frontend opens popup --> Google OAuth consent screen
|
v
User grants scopes --> Google redirects to callback
|
v
Frontend extracts code/state --> tRPC handleCallback mutation
|
v
Backend exchanges code for tokens --> stores in dataSourceConnection
|
v
Periodic sync reads Google Fit REST API --> normalised wellness metricsDeprecation Notice
Google Fit REST API is deprecated in favour of Health Connect (Android). The web OAuth2 flow still works but Google may sunset it. Monitor https://developers.google.com/fit for announcements. See issue #1828 for migration tracking.
2. OAuth2 Setup
Prerequisites
- A Google Cloud project with the Fitness API enabled
- An OAuth 2.0 client ID (Web application type)
- OAuth consent screen configured with required scopes
Google Cloud Console Configuration
- Go to https://console.cloud.google.com/apis/credentials
- Create OAuth 2.0 Client ID (Web application)
- Add authorized redirect URIs:
- Dev:
http://localhost:3000/wellness/google-fit/callback - UAT:
https://uat.professionalperformanceportfolio.com/wellness/google-fit/callback - Prod:
https://app.professionalperformanceportfolio.com/wellness/google-fit/callback
- Dev:
Required OAuth Scopes
https://www.googleapis.com/auth/fitness.activity.read
https://www.googleapis.com/auth/fitness.sleep.read
https://www.googleapis.com/auth/fitness.heart_rate.read
https://www.googleapis.com/auth/fitness.body.read
https://www.googleapis.com/auth/fitness.oxygen_saturation.read3. Environment Variables
| Variable | Description | Example |
|---|---|---|
GOOGLE_FIT_CLIENT_ID | OAuth 2.0 client ID from Google Cloud Console | 123456789.apps.googleusercontent.com |
GOOGLE_FIT_CLIENT_SECRET | OAuth 2.0 client secret | GOCSPX-... |
GOOGLE_FIT_REDIRECT_URI | Callback URL matching Google Cloud Console config | https://uat.professionalperformanceportfolio.com/wellness/google-fit/callback |
Where Values Are Stored
| Environment | Secret Store |
|---|---|
| Local dev | .env file (copy from .env.sample) |
| Tests | .env.test (placeholder values, no real API calls) |
| UAT/Prod | Doppler (ppp/share config) --> injected via Pulumi into Azure Container Apps |
Pulumi Configuration
Google Fit secrets are provisioned as optional environment variables in api/infra-azure/src/index.ts, following the same pattern as Garmin and Fitbit. When absent, the backend disables Google Fit sync and the frontend shows "Coming Soon".
The all-or-nothing validation ensures partial configuration is caught at deploy time:
if (googleFitClientId && (!googleFitClientSecret || !googleFitRedirectUri))
throw new Error('Partial Google Fit config: set all 3 GOOGLE_FIT_* env vars or none');4. Backend Architecture
Key Files
| File | Purpose |
|---|---|
src/services/wellnessService/v2/oauth/googleFitOAuth.ts | OAuth2 flow (auth URL, token exchange, refresh, revoke) |
src/services/wellnessService/v2/providers/googleFit/googleFitClient.ts | REST API client |
src/services/wellnessService/v2/providers/googleFit/googleFitMapper.ts | Maps Google Fit data to normalised wellness metrics |
src/services/wellnessService/v2/providers/googleFit/googleFitTypes.ts | TypeScript types for API responses |
src/services/wellnessService/v2/adapters/providers/googleFitAdapter.ts | Provider adapter for unified sync interface |
src/routers/procedures/wellness/v2/googleFitOAuth.ts | tRPC router (getAuthUrl, handleCallback, disconnect) |
OAuth2 Flow
- getAuthUrl -- generates authorization URL with HMAC-signed state parameter for CSRF protection
- handleCallback -- validates state, exchanges code for tokens, stores in database
- disconnect -- revokes access token at Google, clears tokens from database
Token Management
- Tokens stored in
dataSourceConnectiontable - Auto-refresh:
getValidAccessToken()checks expiry and refreshes proactively - Google does NOT rotate refresh tokens on each refresh (unlike WHOOP)
prompt=consentandaccess_type=offlineensure refresh token is always returned
5. Frontend Integration
The frontend OAuth flow uses a popup window pattern identical to WHOOP and Fitbit:
- User clicks "Connect" on Google Fit card in DataSources
- Frontend calls
getAuthUrlmutation, opens popup to returned URL - Google consent screen displays in popup
- On approval, Google redirects to
/wellness/google-fit/callback GoogleFitCallbackContainerextracts code/state, callshandleCallback- On success, posts
GOOGLE_FIT_OAUTH_COMPLETEto parent window - Parent refetches connection status, popup closes
6. Testing
Unit Tests
All 126 Google Fit tests pass. Tests mock fetch calls -- no real Google API interaction needed.
cd api/backend-ppp
pnpm test src/services/wellnessService/v2/oauth/googleFitOAuth.test.ts
pnpm test src/services/wellnessService/v2/providers/googleFit/
pnpm test src/routers/procedures/wellness/v2/googleFitOAuth.test.tsTest Environment
.env.test contains placeholder values:
GOOGLE_FIT_CLIENT_ID=test-google-fit-client-id
GOOGLE_FIT_CLIENT_SECRET=test-google-fit-client-secret
GOOGLE_FIT_REDIRECT_URI=http://localhost:3000/wellness/google-fit/callback7. Troubleshooting
"GOOGLE_FIT_CLIENT_ID environment variable is required"
Google Fit is not configured for this environment. Set all 3 GOOGLE_FIT_* env vars or leave all unset (backend will disable the integration gracefully).
"Partial Google Fit config"
Only some of the 3 required env vars are set. Set all 3 or remove all of them.
"Google Fit token refresh failed -- please reconnect"
The refresh token was revoked (user removed app access in Google Account settings). User needs to reconnect via the DataSources UI.
"OAuth state parameter has expired"
The OAuth flow took longer than 10 minutes. The user should retry the connection.