canonry

Google Analytics 4 Setup

Canonry integrates with Google Analytics 4 (GA4) via a service account — no OAuth redirect flow required. You grant a service account read-only access to your GA4 property once, and canonry handles the rest.

You can complete the setup via the web dashboard or the CLI — both are documented below.

Prerequisites

Step 1 — Enable the Google Analytics Data API

This is the most commonly missed step. The GA4 Data API must be explicitly enabled in your GCP project.

  1. Open Google Cloud Console and select your project
  2. Navigate to APIs & Services → Library
  3. Search for Google Analytics Data API
  4. Click Enable

Or go directly:

https://console.developers.google.com/apis/api/analyticsdata.googleapis.com/overview?project=YOUR_PROJECT_ID

Note: If you skip this step, connecting will fail with a SERVICE_DISABLED error even if your service account credentials are correct and the account has GA4 property access.

Step 2 — Create a Service Account

  1. In Google Cloud Console: IAM & Admin → Service Accounts → Create Service Account
  2. Name it anything (e.g. canonry-ga4)
  3. Skip the optional GCP role grant — GA4 access is set in GA itself, not here
  4. Click Done
  5. Open the service account → Keys → Add Key → Create new key → JSON
  6. Download the .json key file

Step 3 — Grant Property Access in GA4

The service account needs Viewer (or higher) access to your GA4 property.

  1. Go to Google Analytics
  2. Admin → Property Access Management (in the Property column)
  3. Click + → Add users
  4. Enter the service account email (e.g. canonry-ga4@your-project.iam.gserviceaccount.com)
  5. Role: Viewer → Save

Access propagates within a few seconds to a minute.

Step 4 — Find Your GA4 Property ID

  1. GA4 Admin → Property Settings
  2. Copy the Property ID (a plain number, e.g. 123456789)

This is not the Measurement ID (which starts with G-).

Step 5 — Connect via Canonry

Web UI

  1. Navigate to your project → Traffic tab
  2. Enter your GA4 Property ID (the numeric ID from Step 4)
  3. Click Upload .json key file and select the service account key file you downloaded in Step 2
  4. Click Connect GA4

Canonry verifies the credentials by making a test API call. On success, the page refreshes to show your traffic data.

CLI

canonry ga connect <project> --property-id <id> --key-file ./canonry-ga4.json

Example:

canonry ga connect ainyc --property-id 527609434 --key-file ./canonry-ga4.json

Canonry will verify the credentials by making a test API call. On success:

GA4 connected for project "ainyc" (property 527609434).

Usage

Web UI

The Traffic tab on each project page provides:

CLI

# Sync last 30 days of traffic data
canonry ga sync ainyc

# Show top landing pages by sessions
canonry ga traffic ainyc

# Show landing page coverage with index + citation overlay
canonry ga coverage ainyc

# Connection status
canonry ga status ainyc

# Disconnect
canonry ga disconnect ainyc

Troubleshooting

GA4 API authentication failed — The Google Analytics Data API is not enabled

The API is disabled in your GCP project. Enable it at:

https://console.developers.google.com/apis/api/analyticsdata.googleapis.com/overview?project=YOUR_PROJECT_ID

GA4 API authentication failed — check service account permissions

Either:

Failed to get access token

The JSON key file is invalid or the private key is corrupted. Download a fresh key from the GCP service account console.

JSON file is missing required fields: client_email and private_key

You uploaded the wrong type of credential file. Make sure you downloaded a service account key (IAM & Admin → Service Accounts → Keys), not an OAuth client JSON.

No GA4 connection found

You haven’t connected GA4 to this project yet.

UI: Navigate to the Traffic tab and use the connect form.

CLI: Run canonry ga connect with your property ID and key file.

This site is open source. Improve this page.