Google Analytics (GA4)

Install

See the Install guide for the full setup, including Windows PowerShell.

curl -fsSL https://install.skippr.io/install.sh | shClick to copy

Installing Skippr means accepting the Skippr EULA.

Extracts curated daily fact tables from the Google Analytics Data API (runReport only). Each namespace is one bronze grain with replace-by-date landing semantics. Warehouse SQL/dbt builds channel rollups, WAU, funnels, and pivots — not the source plugin.

This connector does not ingest the GA4 BigQuery export (event-level raw).

How it works

Authenticates with bearer token, OAuth2 refresh, or service account.
For each selected stream, calls runReport with keepEmptyRows: true (default).
Default one calendar day per API request (window_in_days: 1) to limit sampling.
Skips the trailing processing_lag_days (default 1) so incomplete same-day data is not written.
Re-syncs lookback_days (default 3) of mature dates; replace_partition on date overwrites revised metrics.
Optional ecommerce and publisher-ads streams are skipped with a warning when the property lacks those features.

Configuration

Engine skippr.yml (runtime plugin):

yaml

pipelines:
  ga4_analytics:
    data_source: data_sources.ga4
    data_sink: data_sinks.athena

data_sources:
  ga4:
    GoogleAnalytics:
      property_id: "123456789"
      start_date: "2024-01-01"
      stream_profile: full
      lookback_days: 7
      processing_lag_days: 1
      window_in_days: 1
      keep_empty_rows: true
      access_token: ${GA4_ACCESS_TOKEN}

Public skippr.yaml (via skippr connect):

yaml

source:
  kind: google_analytics
  property_id: "123456789"
  start_date: "2024-01-01"
  stream_profile: full
  lookback_days: 7
  access_token: ${GA4_ACCESS_TOKEN}

Field	Default	Description
`property_id`	(required)	GA4 property ID (numeric; without `properties/` prefix)
`start_date`	(required)	First date to sync (`YYYY-MM-DD`)
`end_date`		Last date; omit to sync through yesterday minus lag
`stream_profile`	`full`	`minimal` (4), `standard` (16), or `full` (23 namespaces)
`streams`	profile set	Comma-separated namespaces; overrides profile when set
`lookback_days`	`3`	Mature days to re-fetch each run (raise for long attribution)
`processing_lag_days`	`1`	Skip syncing the last N calendar days
`window_in_days`	`1`	Days per `dateRanges` chunk; >1 risks sampling
`keep_empty_rows`	`true`	Include dimension keys with zero metrics
`access_token`		Bearer token (`${GA4_ACCESS_TOKEN}`)
`oauth_*` / `service_account_json_path`		Alternate auth (see below)

Lag vs lookback vs `window_in_days`

Mechanism	Fixes
`replace_partition` on `date`	Duplicate or stale rows for a day when Google revises metrics
`lookback_days`	Re-pulls recent mature days that may still change
`processing_lag_days`	Avoids writing immature trailing days (today, etc.)
`window_in_days > 1`	Fewer API calls but higher sampling risk — advanced backfills only

Run skippr sync on a schedule with defaults. Do not use window_in_days > 1 for routine accuracy.

Stream profiles

Profile	Namespaces	Use case
`full`	23	Production default
`standard`	16	No demographics, ecommerce, or publisher ads
`minimal`	4	Dev/CI (legacy acquisition + events only)

Full bronze catalog (`stream_profile: full`)

Acquisition & engagement (6)

Namespace	Grain (dimensions)	Metrics
`google_analytics.traffic_acquisition_daily`	`date`, channel, `sessionSource`, `sessionMedium`	`sessions`, `totalUsers`, `conversions`
`google_analytics.traffic_campaign_daily`	`date`, `sessionCampaignName`, source, medium	same
`google_analytics.user_acquisition_daily`	`date`, first-user channel, source, medium	`newUsers`, `totalUsers`
`google_analytics.user_acquisition_campaign_daily`	`date`, first-user campaign, source, medium	same
`google_analytics.events_daily`	`date`, `eventName`	`eventCount`, `totalUsers`
`google_analytics.conversions_daily`	`date`, `eventName`	`conversions`, `totalRevenue`

Audience (2)

Namespace	Grain	Metrics
`google_analytics.audience_daily`	`date`	`activeUsers`, `newUsers`, `sessions`, `engagedSessions`, `averageSessionDuration`
`google_analytics.audience_retention_daily`	`date`	`active1DayUsers`, `active7DayUsers`, `active28DayUsers`

Content (4)

Namespace	Grain	Metrics
`google_analytics.content_pages_daily`	`date`, `pagePath`	`screenPageViews`, `sessions`, `totalUsers`, `engagementRate`
`google_analytics.content_titles_daily`	`date`, `pageTitle`	same
`google_analytics.content_screens_daily`	`date`, `unifiedScreenClass`	same
`google_analytics.content_group_daily`	`date`, `contentGroup`	same

Geo & demographics (5)

Namespace	Grain	Metrics
`google_analytics.geo_daily`	`date`, `country`, `region`, `city`	`sessions`, `totalUsers`, `newUsers`
`google_analytics.demographics_age_daily`	`date`, `userAgeBracket`	same
`google_analytics.demographics_gender_daily`	`date`, `userGender`	same
`google_analytics.demographics_interest_daily`	`date`, `brandingInterest`	same
`google_analytics.demographics_language_daily`	`date`, `language`	same

Tech (3)

Namespace	Grain	Metrics
`google_analytics.tech_daily`	`date`, `deviceCategory`, `operatingSystem`, `browser`	`sessions`, `totalUsers`
`google_analytics.devices_daily`	`date`, `deviceCategory`, `mobileDeviceModel`	same
`google_analytics.tech_platform_daily`	`date`, `platform`, `deviceCategory`	same

Ecommerce (2, optional) — skipped if the property has no ecommerce

Namespace	Grain	Metrics
`google_analytics.ecommerce_items_daily`	`date`, `itemName`	`itemsPurchased`, `itemRevenue`, `itemsAddedToCart`
`google_analytics.ecommerce_categories_daily`	`date`, `itemCategory`	`itemsPurchased`, `itemRevenue`

Publisher ads (1, optional) — skipped if Ads is not linked

Namespace	Grain	Metrics
`google_analytics.publisher_ads_daily`	`date`, `adSourceName`, `adFormat`, `adUnitName`	`publisherAdClicks`, `publisherAdImpressions`, `adUnitExposure`

Each row includes property_id and normalized date (YYYY-MM-DD).

Landing semantics

GA4 daily reports are mutable. This source uses replace_partition on date with lookback_days as the refresh window.

See Source landing semantics.

CLI

bash

skippr connect source google-analytics \
  --property-id 123456789 \
  --start-date 2024-01-01 \
  --stream-profile full \
  --lookback-days 7 \
  --processing-lag-days 1 \
  --window-in-days 1 \
  --access-token ${GA4_ACCESS_TOKEN}

Flag	Description
`--property-id`	GA4 property ID
`--start-date`	First sync date (`YYYY-MM-DD`)
`--end-date`	Last sync date (optional)
`--stream-profile`	`minimal`, `standard`, or `full`
`--lookback-days`	Re-fetch window before checkpoint
`--processing-lag-days`	Skip last N calendar days
`--window-in-days`	Days per API date range (default 1)
`--keep-empty-rows`	Include zero-metric dimension rows
`--streams`	Comma-separated namespaces (overrides profile)
`--access-token`	Bearer token or `${ENV_VAR}`
`--oauth-*` / `--service-account-json-path`	Alternate auth

Authentication

Skippr calls the Google Analytics Data API with a Bearer token. Required OAuth scope:

https://www.googleapis.com/auth/analytics.readonly

The Google account or service account must have Viewer (or higher) on the GA4 property (Admin → Property access management).

Pick one method below. The plugin checks credentials in this order: access_token → OAuth refresh → service account → GOOGLE_APPLICATION_CREDENTIALS.

Both production methods below share the same Google Cloud project prerequisite.

Prerequisite: Google Cloud project + Data API

Open Google Cloud Console and select (or create) a project.
Go to APIs & Services → Library, search for Google Analytics Data API, and click Enable.
Note your GA4 property ID (GA4 Admin → Property settings → Property ID, numeric only — no properties/ prefix).

Service account (recommended for production)

Best for CI, servers, and scheduled skippr sync. Skippr reads the JSON key and mints short-lived access tokens automatically. You do not set GA4_ACCESS_TOKEN.

1. Create the service account (Cloud Console)

IAM & Admin → Service Accounts → Create service account.
Name it (for example skippr-ga4-read) and click Create and continue.
Grant this service account access to project — optional for GA4 Data API reads; property-level access in GA4 (next step) is what matters. Click Done.
Open the new service account → Keys → Add key → Create new key → JSON → Create. Store the downloaded .json file securely (treat it like a password).

The key file contains a field client_email, for example skippr-ga4-read@my-project.iam.gserviceaccount.com. You need that email in GA4.

2. Grant the service account access to the GA4 property

Service accounts do not inherit your personal Google login. Add the robot account explicitly:

In Google Analytics, open the target property.
Admin (gear) → Property access management.
+ → Add users.
Paste the service account email from the JSON (client_email), for example skipprd@optimistic-jet-274810.iam.gserviceaccount.com.
Role: Viewer (minimum for read-only Data API). Turn off Notify new users by email (there is no inbox for a service account). Save.

Without this step, sync fails with 403 even if the key file is valid.

2a. UI error: “This email doesn’t match a Google Account”

The GA4 Add users dialog only validates human Google accounts (@gmail.com, Google Workspace). Many properties show an error for *.iam.gserviceaccount.com even though the address is correct. That is a known GA4 UI limitation, not a problem with your service account.

Fastest workaround — use OAuth refresh instead: authorize with the same Google account that already has GA4 Administrator access. Skippr does not need the service account on the property for that path.

If you must use the service account, grant access with the Google Analytics Admin API (as a GA4 admin user):

In Cloud Console, enable Google Analytics Admin API (same project as the service account).
Authenticate as a user who is Administrator on the GA4 property:

bash

gcloud auth application-default login \
  --scopes=https://www.googleapis.com/auth/analytics.manage.users,https://www.googleapis.com/auth/cloud-platform

Create a property access binding (replace PROPERTY_ID and the service account email):

bash

export PROPERTY_ID="123456789"   # numeric GA4 property ID
export SA_EMAIL="skipprd@optimistic-jet-274810.iam.gserviceaccount.com"

curl -s -X POST \
  "https://analyticsadmin.googleapis.com/v1alpha/properties/${PROPERTY_ID}/accessBindings" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  -d "{\"user\": \"${SA_EMAIL}\", \"roles\": [\"predefinedRoles/viewer\"]}"

In GA4 Property access management, confirm the service account appears in the user list (it may show up after the API call even when the UI refused manual entry).

If the API returns an error, use OAuth refresh for now or ask a GA4 account administrator to run the same curl at account level (parent=accounts/ACCOUNT_ID).

3. Configure Skippr

Option A — path in config (explicit, works everywhere):

yaml

# skippr.yml (engine / runtime plugin)
data_sources:
  ga4:
    GoogleAnalytics:
      property_id: "123456789"
      start_date: "2024-01-01"
      service_account_json_path: /secure/path/skippr-ga4-key.json

yaml

# skippr.yaml (public config via translate)
source:
  kind: google_analytics
  property_id: "123456789"
  start_date: "2024-01-01"
  service_account_json_path: /secure/path/skippr-ga4-key.json

Option B — environment variable (common in containers):

bash

export GOOGLE_APPLICATION_CREDENTIALS="/secure/path/skippr-ga4-key.json"

Omit service_account_json_path when using GOOGLE_APPLICATION_CREDENTIALS; Skippr picks up the path automatically.

CLI:

bash

skippr connect source google-analytics \
  --property-id 123456789 \
  --start-date 2024-01-01 \
  --service-account-json-path /secure/path/skippr-ga4-key.json

Do not set access_token when using a service account.

4. Verify

bash

skippr sync

If auth fails, confirm the Data API is enabled, the JSON path is readable, and the service account email appears under property access management.

OAuth refresh (user-delegated automation)

Use when a human Google account should own access (not a robot account), for example a workspace user who already has GA4 access. Skippr stores a refresh token and requests a new access token on each sync. You do not set GA4_ACCESS_TOKEN.

All four OAuth fields must be set for Skippr to use this path: oauth_token_url, oauth_client_id, oauth_client_secret, oauth_refresh_token.

Cloud Console → APIs & Services → OAuth consent screen.
User type:
- Internal — only if you use Google Workspace and the GA4 property is in the same org. No Google verification required for coworkers.
- External — personal Gmail or mixed accounts. For your own testing, leave publishing status as Testing (do not click Publish app).
Fill required app name and support email.
Scopes → Add or remove scopes → add manually: https://www.googleapis.com/auth/analytics.readonly
Google may show “needs verification” for External apps — that applies only if you publish to the public. In Testing mode you can use the scope without verification for accounts listed as test users.
Test users (required for External + Testing): add every Google account that will run Playground / skippr sync (your @gmail.com or Workspace email).
Save. You do not need Google’s app review for a private Skippr pipeline while status stays Testing and you are a listed test user.

2. Create an OAuth client ID

APIs & Services → Credentials → Create credentials → OAuth client ID.
Application type: Web application (works with the OAuth Playground below).
Name it (for example skippr-ga4-oauth).
Authorized redirect URIs → add:
https://developers.google.com/oauthplayground
Create → copy the Client ID and Client secret.

3. Obtain a refresh token (one-time)

Use the OAuth 2.0 Playground with your client:

Click the gear icon (top right) → check Use your own OAuth credentials → paste Client ID and Client secret → Close.
In the left panel, scroll to Google Analytics Data API v1 or paste into the input box: https://www.googleapis.com/auth/analytics.readonly
Click Authorize APIs → sign in with the same Google user that has Viewer access on the GA4 property.
Click Exchange authorization code for tokens.
Copy the Refresh token from the response. Store it in a secret manager or env var — it does not expire unless revoked.

If no refresh token appears, revoke prior access at Google Account permissions, then repeat with the gear menu option Force prompt (if shown) so Google issues a new refresh token.

4. Configure Skippr

Set secrets via environment variables (recommended):

bash

export GA4_OAUTH_CLIENT_ID="....apps.googleusercontent.com"
export GA4_OAUTH_CLIENT_SECRET="...."
export GA4_OAUTH_REFRESH_TOKEN="1//...."

yaml

# skippr.yml
data_sources:
  ga4:
    GoogleAnalytics:
      property_id: "123456789"
      start_date: "2024-01-01"
      oauth_token_url: https://oauth2.googleapis.com/token
      oauth_client_id: ${GA4_OAUTH_CLIENT_ID}
      oauth_client_secret: ${GA4_OAUTH_CLIENT_SECRET}
      oauth_refresh_token: ${GA4_OAUTH_REFRESH_TOKEN}

oauth_token_url must be https://oauth2.googleapis.com/token for standard Google OAuth clients.

Do not open this URL in a browser

oauth2.googleapis.com/token is a POST-only API endpoint. Opening it in Chrome/Safari shows “page can’t be found” — that is normal. Put the URL in skippr.yml only; Skippr (or curl below) sends the refresh token there in the background.

CLI:

bash

skippr connect source google-analytics \
  --property-id 123456789 \
  --start-date 2024-01-01 \
  --oauth-token-url https://oauth2.googleapis.com/token \
  --oauth-client-id "${GA4_OAUTH_CLIENT_ID}" \
  --oauth-client-secret "${GA4_OAUTH_CLIENT_SECRET}" \
  --oauth-refresh-token "${GA4_OAUTH_REFRESH_TOKEN}"

Do not set access_token when using refresh credentials.

5. Verify

Optional — confirm the refresh token works:

bash

curl -s -X POST https://oauth2.googleapis.com/token \
  -d "client_id=${GA4_OAUTH_CLIENT_ID}" \
  -d "client_secret=${GA4_OAUTH_CLIENT_SECRET}" \
  -d "refresh_token=${GA4_OAUTH_REFRESH_TOKEN}" \
  -d "grant_type=refresh_token" | jq -r .access_token

Then run skippr sync. On 401, the refresh token may have been revoked; repeat section 3.

Service account vs OAuth refresh

	Service account	OAuth refresh
Identity	Robot (`...@....iam.gserviceaccount.com`)	Human Google user
GA4 access	Add SA email in property access management	User must already have property access
Secrets	JSON key file	Client ID, secret, refresh token
Typical use	Production ETL, CI, VMs	When policy blocks service accounts on GA4

Bearer access token (`GA4_ACCESS_TOKEN`)

GA4_ACCESS_TOKEN is the OAuth 2.0 access token string (starts with ya29. for Google). It is not a separate API key from the GA4 UI, and it expires (typically after about one hour). Use this for local testing; prefer a service account or refresh token for automation.

Option A — OAuth 2.0 Playground (quickest for a first sync)

Enable the Google Analytics Data API and create an OAuth client ID in Cloud Console (same as refresh flow above).
Open OAuth 2.0 Playground.
Gear icon → Use your own OAuth credentials → paste client ID and secret.
Step 1: input scope https://www.googleapis.com/auth/analytics.readonly → Authorize APIs → sign in with a user that has access to the property.
Step 2: Exchange authorization code for tokens → copy Access token.
Export and run:

bash

export GA4_ACCESS_TOKEN="ya29...."   # paste access token from Step 2
skippr sync

Your config can reference the env var:

yaml

access_token: ${GA4_ACCESS_TOKEN}

skippr connect defaults to ${GA4_ACCESS_TOKEN} when you do not pass --access-token.

Option B — gcloud (if you already use Google Cloud CLI)

bash

gcloud auth application-default login \
  --scopes=https://www.googleapis.com/auth/analytics.readonly,https://www.googleapis.com/auth/cloud-platform

export GA4_ACCESS_TOKEN="$(gcloud auth application-default print-access-token)"

The token expires; re-run print-access-token when sync returns 401.

Option C — curl (when you already have a refresh token)

bash

curl -s -X POST https://oauth2.googleapis.com/token \
  -d client_id="${GA4_OAUTH_CLIENT_ID}" \
  -d client_secret="${GA4_OAUTH_CLIENT_SECRET}" \
  -d refresh_token="${GA4_OAUTH_REFRESH_TOKEN}" \
  -d grant_type=refresh_token \
  | jq -r .access_token

Set GA4_ACCESS_TOKEN to the printed value, or configure the refresh fields in skippr.yml so Skippr refreshes automatically (preferred).

Security

Do not commit tokens, refresh tokens, or JSON keys in git. Use ${ENV_VAR} in config.
Rotate compromised credentials in Cloud Console and GA4 property access.

Recommended destination

Athena (S3 + Glue) enforces replace_partition. S3 paths look like bronze/google_analytics.events_daily/date=2024-01-15/. Run skippr discover after the first sync.

Troubleshooting

Symptom	Fix
This email doesn’t match a Google Account (service account)	GA4 UI cannot add `*.iam.gserviceaccount.com` on many properties — use OAuth refresh or Admin API access binding
401 / 403	Regenerate `GA4_ACCESS_TOKEN` (expired), confirm `analytics.readonly` scope, and property Viewer access (or valid access binding for the service account)
`GA4 requires access_token...`	Set `GA4_ACCESS_TOKEN`, OAuth refresh fields, or service account path — see Authentication
Empty ecommerce/ads tables	Enable features in GA4; streams are optional and may be skipped
Stale metrics	Confirm `replace_partition`; increase `lookback_days`
Sampling concerns	Keep `window_in_days: 1`
OAuth scope needs verification / can’t publish app	Keep consent screen in Testing; add yourself under Test users; do not publish. Or use Internal if on Workspace.
`gcloud auth application-default login`: This app is blocked	Workspace admin may block third-party Google sign-in, or the wrong account is signed in. Skip `gcloud` for Skippr OAuth refresh — it is not required. Use Playground + env vars, or a service account JSON key.
Playground / OAuth access blocked	Same as above: Testing + test users; try a personal Gmail GCP project; ask Workspace admin to allow your OAuth app or “Google Cloud SDK”.

Offline dev: set SKIPPR_GA4_FIXTURE_DIR to JSON fixtures named {namespace_with_underscores}_{YYYYMMDD}.json.

Google Analytics (GA4) ​

Install ​

How it works ​

Configuration ​

Lag vs lookback vs window_in_days ​

Stream profiles ​

Full bronze catalog (stream_profile: full) ​

Landing semantics ​

CLI ​

Authentication ​

Prerequisite: Google Cloud project + Data API ​

Service account (recommended for production) ​

1. Create the service account (Cloud Console) ​

2. Grant the service account access to the GA4 property ​

2a. UI error: “This email doesn’t match a Google Account” ​

3. Configure Skippr ​

4. Verify ​

OAuth refresh (user-delegated automation) ​

1. Configure the OAuth consent screen ​

2. Create an OAuth client ID ​

3. Obtain a refresh token (one-time) ​

4. Configure Skippr ​

5. Verify ​

Service account vs OAuth refresh ​

Bearer access token (GA4_ACCESS_TOKEN) ​

Option A — OAuth 2.0 Playground (quickest for a first sync) ​

Option B — gcloud (if you already use Google Cloud CLI) ​

Option C — curl (when you already have a refresh token) ​

Security ​

Recommended destination ​

Troubleshooting ​

Next steps ​

Google Analytics (GA4)

Install

How it works

Configuration

Lag vs lookback vs `window_in_days`

Stream profiles

Full bronze catalog (`stream_profile: full`)

Landing semantics

CLI

Authentication

Prerequisite: Google Cloud project + Data API

Service account (recommended for production)

1. Create the service account (Cloud Console)

2. Grant the service account access to the GA4 property

2a. UI error: “This email doesn’t match a Google Account”

3. Configure Skippr

4. Verify

OAuth refresh (user-delegated automation)

1. Configure the OAuth consent screen

2. Create an OAuth client ID

3. Obtain a refresh token (one-time)

4. Configure Skippr

5. Verify

Service account vs OAuth refresh

Bearer access token (`GA4_ACCESS_TOKEN`)

Option A — OAuth 2.0 Playground (quickest for a first sync)

Option B — gcloud (if you already use Google Cloud CLI)

Option C — curl (when you already have a refresh token)

Security

Recommended destination

Troubleshooting

Next steps