# Google Analytics 4

SEO Utils integrates with Google Analytics 4 (GA4) to sync organic search metrics — sessions, users, bounce rate, and conversion data (Key Events) — into your local database. This data powers the **Key Events** insight in the Organic Rank Tracker, showing you which tracked keywords are driving conversions.

{% hint style="info" %}
GA4 data is synced automatically once per day and stored locally. Your data never leaves your machine.
{% endhint %}

## Prerequisites

Before setting up GA4 integration, you need:

* A **Google Service Account** added to SEO Utils (see [Google Service Accounts](https://help.seoutils.app/guide/google-service-accounts))
* A **GA4 property** with your website configured
* The service account must have **Viewer** access to your GA4 property

## Step 1: Enable Required APIs

You need to enable two Google APIs in the Google Cloud project that your service account belongs to.

{% stepper %}
{% step %}
**Enable the Google Analytics Data API**

This API is used to sync metrics (sessions, conversions, etc.) from GA4.

* Go to the [Google Cloud Console](https://console.cloud.google.com/)
* Select the project your service account belongs to
* Navigate to **APIs & Services → Library**
* Search for **"Google Analytics Data API"**
* Click **Enable**

<figure><img src="https://1176579443-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2DwV6sJBiKjUHMDggb4d%2Fuploads%2F1emLf5jqz6MeD6xIxPBv%2FXnapper-2026-03-30-21.26.11.png?alt=media&#x26;token=666fc2ca-a4eb-4e39-831a-cc6f6c112f01" alt="" width="563"><figcaption><p>Enable the Google Analytics Data API in Google Cloud Console</p></figcaption></figure>
{% endstep %}

{% step %}
**Enable the Google Analytics Admin API**

This API is used to discover your GA4 properties and auto-match them to tracked domains.

* In the same project, go to **APIs & Services → Library**
* Search for **"Google Analytics Admin API"**
* Click **Enable**

<figure><img src="https://1176579443-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2DwV6sJBiKjUHMDggb4d%2Fuploads%2FrIMngPkIVRkpnnGaLIPN%2FXnapper-2026-03-30-21.26.50.png?alt=media&#x26;token=2ab78459-04ad-4980-899a-3a643aaf9e02" alt="" width="563"><figcaption><p>Enable the Google Analytics Admin API in Google Cloud Console</p></figcaption></figure>
{% endstep %}
{% endstepper %}

{% hint style="warning" %}
Both APIs must be enabled in the **same Google Cloud project** that your service account belongs to. APIs are enabled at the project level, not per service account.
{% endhint %}

## Step 2: Grant Service Account Access to GA4

Your service account needs permission to read data from your GA4 property.

{% stepper %}
{% step %}
**Copy Your Service Account Email**

In SEO Utils, go to the **Google Service Accounts** page and copy the service account email (e.g., `project-932@project-1608918721837.iam.gserviceaccount.com`).
{% endstep %}

{% step %}
**Add the Service Account to GA4**

You can grant access at the **property level** or **account level**:

{% tabs %}
{% tab title="Property Level (Single Property)" %}

* Go to [Google Analytics](https://analytics.google.com/)
* Click the **gear icon** (Admin) at the bottom-left
* Under **Property**, click **Property Access Management**
* Click the **+** button → **Add users**
* Paste your service account email
* Set the role to **Viewer**
* Click **Add**
  {% endtab %}

{% tab title="Account Level (All Properties)" %}
If you want the service account to access **all properties** under your GA4 account:

* Go to [Google Analytics](https://analytics.google.com/)
* Click the **gear icon** (Admin) at the bottom-left
* Under **Account**, click **Account Access Management**
* Click the **+** button → **Add users**
* Paste your service account email
* Set the role to **Viewer**
* Click **Add**

This grants access to all current and future properties under that account.
{% endtab %}
{% endtabs %}

<figure><img src="https://1176579443-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2DwV6sJBiKjUHMDggb4d%2Fuploads%2FzgnAFCmtSnQi25nDzaIs%2FXnapper-2026-03-30-21.28.22.png?alt=media&#x26;token=5861239b-6f3f-4fa9-a36d-87b7494c1392" alt=""><figcaption><p>Add the service account email as a Viewer in GA4 Property Access Management</p></figcaption></figure>
{% endstep %}
{% endstepper %}

{% hint style="info" %}
**Viewer** permission is sufficient. SEO Utils only reads data from GA4 — it never modifies your analytics configuration.
{% endhint %}

## Step 3: Add a GA4 Property in SEO Utils

{% stepper %}
{% step %}
**Navigate to Google Analytics 4**

In SEO Utils, find **Google Analytics 4** in the left sidebar and click **Add Property**.

<figure><img src="https://1176579443-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2DwV6sJBiKjUHMDggb4d%2Fuploads%2FW0xUcuhyE7qv6K9z6m6o%2FXnapper-2026-03-30-21.29.43.png?alt=media&#x26;token=c433f2b3-ca09-469b-9a1b-c98f56826f68" alt="" width="375"><figcaption><p>Google Analytics 4 section in the sidebar</p></figcaption></figure>
{% endstep %}

{% step %}
**Select a Service Account**

Choose the Google Service Account that has access to your GA4 property. SEO Utils will fetch all GA4 properties the account can access.

<figure><img src="https://1176579443-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2DwV6sJBiKjUHMDggb4d%2Fuploads%2F0XQze7Y9Lf1P41N6TAJY%2FXnapper-2026-03-30-21.30.28.png?alt=media&#x26;token=70a97f45-b3c1-4612-9044-fead283c78c3" alt=""><figcaption><p>Select a service account to list accessible GA4 properties</p></figcaption></figure>
{% endstep %}

{% step %}
**Select a GA4 Property**

Pick your GA4 property from the dropdown. The **Mapped Domain** field will auto-fill based on the property's website URL — this links the GA4 data to your Organic Rank Tracker reports.

Set the **Initial Backfill** to choose how many days of historical data to import on first sync (default: 90 days). GA4 free tier retains 2 months of data by default, or up to 14 months if you've enabled extended retention in your GA4 property settings.

<figure><img src="https://1176579443-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2DwV6sJBiKjUHMDggb4d%2Fuploads%2FI3ELOwZd2qdbku9dLGOM%2FXnapper-2026-03-30-21.31.51.png?alt=media&#x26;token=1036a6d8-7f80-42dc-b7ac-41887a35e07f" alt=""><figcaption><p>Select a GA4 property, confirm the mapped domain, and set the backfill period</p></figcaption></figure>

{% hint style="info" %}
The mapped domain should match the target domain in your Organic Rank Tracker report. For example, if your rank tracker tracks `example.com`, the mapped domain should also be `example.com`.
{% endhint %}
{% endstep %}

{% step %}
**Manage Your Properties**

After adding a property, SEO Utils will automatically start syncing historical data. You can see it in the **GA4 Properties** list. From here you can:

* **Enable/disable sync** — Toggle whether this property syncs automatically once per day
* **Sync Now** — Trigger an immediate data sync
* **Edit domain** — Click the domain to change the mapped domain
* **Remove** — Delete the property and all synced GA4 data. You can re-add the property later to sync again

{% hint style="warning" %}
Removing a GA4 property deletes all synced metrics data for that property. Key Events badges in the Organic Rank Tracker will no longer appear for keywords associated with this property. The data can be re-synced by adding the property again.
{% endhint %}

<figure><img src="https://1176579443-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2DwV6sJBiKjUHMDggb4d%2Fuploads%2FfIEysAWqe1PAtoXLLLW6%2FXnapper-2026-03-30-21.33.28.png?alt=media&#x26;token=ec730c5d-713f-423a-8423-35f755819081" alt=""><figcaption><p>GA4 Properties list showing connected properties with sync status</p></figcaption></figure>
{% endstep %}
{% endstepper %}

## Syncing Data

GA4 data syncs automatically **once per day**. You can also click **"Sync Now"** in the GA4 Properties list to trigger an immediate sync.

SEO Utils only syncs **organic search traffic** — visits from Google organic search results. For each landing page, per day:

| Metric               | Description                                                     |
| -------------------- | --------------------------------------------------------------- |
| Sessions             | Number of organic search sessions                               |
| Engaged Sessions     | Sessions with meaningful engagement                             |
| Bounce Rate          | Percentage of single-page sessions                              |
| Avg. Engagement Time | Average time users spent on the page                            |
| Users                | Total unique users from organic search                          |
| New Users            | First-time visitors from organic search                         |
| Key Events           | Conversion events (purchases, sign-ups, form submissions, etc.) |
| Revenue              | Total revenue from organic search sessions                      |

## How GA4 Data Powers Key Events

The primary use of GA4 data is the **Key Events** insight in the [Organic Rank Tracker](https://help.seoutils.app/guide/organic-rank-tracker). When GA4 data is synced, the rank tracker can show you which keywords are associated with pages that generate conversions.

For example, if the keyword "deep cleaning cambridge" ranks on your `/cambridge` page, and that page had 3 conversions in GA4, the keyword will display a **"3 Key Events"** badge in the rank tracker.

This helps you:

* **Identify revenue-driving keywords** — See which keywords are associated with actual business outcomes
* **Prioritize SEO efforts** — Focus on keywords that drive conversions, not just traffic
* **Correlate rank changes with conversions** — Spot when a ranking improvement leads to more conversions

{% hint style="info" %}
Key Events attribution works by matching the rank tracker's keyword → page mapping with GA4's landing page → conversion data. For the most accurate results, also connect [Google Search Console](https://help.seoutils.app/guide/google-search-console) to provide authoritative keyword-to-page click data.
{% endhint %}

## Troubleshooting

<details>

<summary>"Google Analytics Data API has not been used in project" error</summary>

You need to enable the **Google Analytics Data API** in your Google Cloud project. Visit the link in the error message to enable it, then wait a minute and try again.

</details>

<details>

<summary>"Google Analytics Admin API has not been used in project" error</summary>

You need to enable the **Google Analytics Admin API** in your Google Cloud project. This is a separate API from the Data API — both need to be enabled. Visit the link in the error message to enable it.

</details>

<details>

<summary>No properties found after clicking "Discover Properties"</summary>

Your service account doesn't have access to any GA4 properties. Grant the service account **Viewer** access in GA4's Property Access Management (or Account Access Management for all properties).

</details>

<details>

<summary>Data syncs successfully but shows 0 rows</summary>

This is normal if your site has very low organic search traffic, or if GA4 data hasn't finished processing yet (24-72 hour delay). The sync will pick up the data on the next run.

</details>

<details>

<summary>Sync failed with authentication error</summary>

* Verify your service account still has access to the GA4 property
* Check that the service account key hasn't expired or been deleted in Google Cloud Console
* Re-upload the service account key file if needed

</details>