Skip to content

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 metrics

Deprecation 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 ​

  1. A Google Cloud project with the Fitness API enabled
  2. An OAuth 2.0 client ID (Web application type)
  3. OAuth consent screen configured with required scopes

Google Cloud Console Configuration ​

  1. Go to https://console.cloud.google.com/apis/credentials
  2. Create OAuth 2.0 Client ID (Web application)
  3. 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

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.read

3. Environment Variables ​

VariableDescriptionExample
GOOGLE_FIT_CLIENT_IDOAuth 2.0 client ID from Google Cloud Console123456789.apps.googleusercontent.com
GOOGLE_FIT_CLIENT_SECRETOAuth 2.0 client secretGOCSPX-...
GOOGLE_FIT_REDIRECT_URICallback URL matching Google Cloud Console confighttps://uat.professionalperformanceportfolio.com/wellness/google-fit/callback

Where Values Are Stored ​

EnvironmentSecret Store
Local dev.env file (copy from .env.sample)
Tests.env.test (placeholder values, no real API calls)
UAT/ProdDoppler (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 ​

FilePurpose
src/services/wellnessService/v2/oauth/googleFitOAuth.tsOAuth2 flow (auth URL, token exchange, refresh, revoke)
src/services/wellnessService/v2/providers/googleFit/googleFitClient.tsREST API client
src/services/wellnessService/v2/providers/googleFit/googleFitMapper.tsMaps Google Fit data to normalised wellness metrics
src/services/wellnessService/v2/providers/googleFit/googleFitTypes.tsTypeScript types for API responses
src/services/wellnessService/v2/adapters/providers/googleFitAdapter.tsProvider adapter for unified sync interface
src/routers/procedures/wellness/v2/googleFitOAuth.tstRPC router (getAuthUrl, handleCallback, disconnect)

OAuth2 Flow ​

  1. getAuthUrl -- generates authorization URL with HMAC-signed state parameter for CSRF protection
  2. handleCallback -- validates state, exchanges code for tokens, stores in database
  3. disconnect -- revokes access token at Google, clears tokens from database

Token Management ​

  • Tokens stored in dataSourceConnection table
  • Auto-refresh: getValidAccessToken() checks expiry and refreshes proactively
  • Google does NOT rotate refresh tokens on each refresh (unlike WHOOP)
  • prompt=consent and access_type=offline ensure refresh token is always returned

5. Frontend Integration ​

The frontend OAuth flow uses a popup window pattern identical to WHOOP and Fitbit:

  1. User clicks "Connect" on Google Fit card in DataSources
  2. Frontend calls getAuthUrl mutation, opens popup to returned URL
  3. Google consent screen displays in popup
  4. On approval, Google redirects to /wellness/google-fit/callback
  5. GoogleFitCallbackContainer extracts code/state, calls handleCallback
  6. On success, posts GOOGLE_FIT_OAUTH_COMPLETE to parent window
  7. 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.

bash
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.ts

Test 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/callback

7. 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.

Internal documentation — org members only