Skip to main content

​
Overview

Integrate Google Analytics 4 (GA4) to enable traffic-based priority for cache warming and job filtering. Adapt uses GA4 page view data to identify your most-visited pages and warm their cache first. Key Features:
  • OAuth 2.0 authentication with Google accounts
  • GA4 Data API integration for page view metrics
  • Traffic-based task prioritisation (7, 28, and 180-day periods)
  • Per-organisation property configuration
  • Automatic token refresh

​
OAuth Flow

​
Initiating Connection

Start the OAuth flow by making a POST request to initiate the connection: 
POST /v1/integrations/google
Authorization: Bearer <your_jwt_token>
Response: 
{
  "status": "success",
  "data": {
    "auth_url": "https://accounts.google.com/o/oauth2/v2/auth?client_id=..."
  },
  "message": "Redirect to this URL to connect Google Analytics"
}
Redirect the user to the auth_url to complete authorisation.

​
Required OAuth Scopes

Adapt requests the following scopes from Google:
  • https://www.googleapis.com/auth/analytics.readonly - Read access to Analytics data
  • https://www.googleapis.com/auth/userinfo.email - User email for account linking
Adapt uses offline access with consent prompt to obtain a refresh token, allowing long-term access to analytics data without repeated login.

​
OAuth Callback

After user authorisation, Google redirects back to: 
/v1/integrations/google/callback?code=...&state=...
The callback handler:
  1. Validates the state parameter (HMAC-signed)
  2. Exchanges the authorisation code for access and refresh tokens
  3. Fetches available GA4 accounts and properties
  4. Creates a temporary session for property selection
  5. Redirects to settings page for property configuration

​
Property Configuration

​
Listing Accounts and Properties

After OAuth, fetch available GA4 accounts: 
GET /v1/integrations/google/{connection_id}
Authorization: Bearer <your_jwt_token>
Response: 
{
  "status": "success",
  "data": {
    "connection": {
      "id": "conn_123",
      "organisation_id": "org_456",
      "email": "[email protected]",
      "accounts": [
        {
          "account": "accounts/123456",
          "display_name": "My Company"
        }
      ],
      "property_id": null,
      "property_name": null,
      "created_at": "2023-05-18T10:00:00Z"
    }
  }
}

​
Saving Selected Property

Once you’ve selected a GA4 property, save it to your organisation: 
POST /v1/integrations/google/save-property
Authorization: Bearer <your_jwt_token>
Content-Type: application/json

{
  "connection_id": "conn_123",
  "property_id": "properties/987654321",
  "property_name": "My Website"
}
Response: 
{
  "status": "success",
  "data": {
    "connection": {
      "id": "conn_123",
      "organisation_id": "org_456",
      "property_id": "properties/987654321",
      "property_name": "My Website",
      "updated_at": "2023-05-18T10:05:00Z"
    }
  }
}

​
Analytics Data Integration

​
Page View Metrics

Once configured, Adapt automatically fetches page view data for your crawled pages across three time periods:
  • 7 days - Recent traffic patterns
  • 28 days - Monthly traffic trends
  • 180 days - Long-term page popularity

​
Task Prioritisation

When listing tasks, you can sort by analytics metrics: 
GET /v1/jobs/{job_id}/tasks?sort=-ga4_page_views_7d
Authorization: Bearer <your_jwt_token>
Available sort fields:
  • ga4_page_views_7d - Page views in last 7 days
  • ga4_page_views_28d - Page views in last 28 days
  • ga4_page_views_180d - Page views in last 180 days
Sort by -ga4_page_views_7d (descending) to warm cache for your most-visited pages first.

​
Data Fetching

Adapt fetches GA4 data in batches:
  • Initial batch: 100 pages
  • Medium batches: 1,000 pages
  • Large batches: 50,000 pages (after 10,000 offset)
The GA4 Data API supports up to 250,000 rows per request, but Adapt uses conservative batch sizes to avoid timeout issues.

​
Managing Connections

​
List Connections

View all Google Analytics connections for your organisation: 
GET /v1/integrations/google
Authorization: Bearer <your_jwt_token>

​
Delete Connection

Remove a Google Analytics connection: 
DELETE /v1/integrations/google/{connection_id}
Authorization: Bearer <your_jwt_token>
This removes the connection and revokes access to analytics data. Page view metrics are retained but won’t be updated.

​
Security

​
Token Storage

All OAuth tokens are stored securely in Supabase Vault:
  • Refresh tokens - Encrypted in vault.secrets table
  • Access tokens - Cached in memory, refreshed automatically
  • Organisation isolation - Tokens scoped per organisation via RLS

​
Token Refresh

Access tokens expire after 1 hour. Adapt automatically refreshes them using the stored refresh token when making GA4 API requests. If refresh fails (e.g., user revoked access), the connection status is marked as refresh_failed and you’ll need to re-authorise.

​
Troubleshooting

​
No Analytics Data Appearing

Ensure you’ve completed the property selection step after OAuth. Check /v1/integrations/google to verify property_id is set.
GA4 property IDs must match exactly between your GA4 admin settings and Adapt. Format: properties/123456789
Verify your Google account has at least Viewer role on the GA4 property.

​
OAuth Errors

The OAuth state parameter prevents CSRF attacks. If validation fails:
  • Ensure cookies are enabled
  • Don’t bookmark the OAuth callback URL
  • Start the flow from /v1/integrations/google each time
If automatic token refresh fails:
  1. Delete the connection
  2. Re-initiate OAuth flow
  3. Grant consent again for offline access

​
API Rate Limits

Google Analytics Data API has quota limits:
  • Core Requests: 40,000 per day per project
  • Tokens per request: 4,000 per hour
Adapt batches requests efficiently and respects these limits automatically.
Large sites (>100,000 pages) may hit quota limits during initial data fetch. Adapt will retry failed requests with exponential backoff.

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us