> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mainwp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Analytics

> The MainWP Google Analytics Extension gives you the ability to view your Google Analytics data for your child sites in your MainWP Dashboard. It adds a widget to your main dashboard where you can monitor Google Analytics data from.

## What You'll Learn

* Connecting Google Analytics via Sign In with Google or Service Account JSON
* Assigning GA4 properties to child sites
* Viewing visitor data across all child sites
* Managing account refresh and reconnection

***

> [!NOTE]
>
> **Integration Add-on** - This add-on extends MainWP to work with Google Analytics. Requires Google Analytics to be installed on your child sites.

[Google Analytics video tutorial](https://www.youtube.com/embed/JX0lM20ShjA)

The [MainWP Google Analytics Extension](https://mainwp.com/extension/google-analytics/) gives you valuable insights into your visitors' traffic patterns and campaign performance so you can optimize your strategy and user experience.

## Use this Extension To Track:

* Views
* Views by Page
* Users
* Users by Device
* Users by Country
* New Users
* Average Engagement Time
* Sessions by Source

**Requirements**

* PHP 8.3 or higher on the Dashboard server when using MainWP Dashboard 6.4 (see [System Requirements](https://docs.mainwp.com/advanced/miscellaneous/mainwp-system-requirements.md))
* Google Analytics (GA4) installed on your child sites
* For JSON import: Google Analytics Admin API, Google Analytics API, and Google Analytics Data API

## Connect your Google Analytics Account

You can connect Google Analytics in two ways. Use whichever fits your setup (you can use both):

![Google Analytics Add Account page with Sign In with Google and Import JSON File options](https://mintcdn.com/mainwp/N50GAiWDBzkdyfTh/images/add-ons/sign-with-google.png?fit=max\&auto=format\&n=N50GAiWDBzkdyfTh\&q=85\&s=90c3842f4f78531e2b7d12707d5611a5)

### Option A: Sign In with Google

1. In your MainWP Dashboard, go to **MainWP > Add-ons > Google Analytics > Add Account**.
2. Keep the **Sign In with Google** tab selected, then click **Sign In with Google**.
3. Complete Google authorization in the popup window.
4. In **Select Google Analytics Project**, choose the account(s) you want to connect, then click **Continue**.
5. In **Confirm Google Analytics Connection**, review the summary and click **Confirm**.
6. Your account will appear under **Manage Accounts** in **Accounts by Sign In**.

**Notes**

* This flow uses MainWP Bridge (`bridge.mainwp.com`) for secure authentication. See [MainWP Bridge](https://docs.mainwp.com/advanced/miscellaneous/mainwp-bridge.md) and the [MainWP Bridge Privacy Policy](https://mainwp.com/mainwp-bridge-privacy-policy).
* Before any OAuth action, the extension checks that your Dashboard's WordPress REST API root (`/wp-json/`) is reachable. If it isn't, the **Sign In with Google**, **Continue**, **Confirm**, **Reconnect Account**, and refresh buttons are disabled and an in-page notice links to [WordPress REST API does not respond](https://docs.mainwp.com/troubleshooting/wordpress-rest-api-does-not-respond.md). Use **Import JSON File** to connect in the meantime.

> [!WARNING]
>
> If HTTP basic auth protects your MainWP Dashboard before it has paired with MainWP Bridge, **Sign In with Google** can fail because MainWP Bridge must be able to reach your Dashboard. If you need to keep HTTP basic auth enabled, use **Import JSON File** instead.

### Option B: Connect a Service Account (JSON file)

**Step 1 - Enable required APIs in Google Cloud Console**

**1. Go to [https://console.cloud.google.com](https://console.cloud.google.com) and create a new project (optional).**

![Google Cloud Console new project creation dialog](https://mintcdn.com/mainwp/m5iWPkGmGTv3i5YV/images/add-ons/ga-new-project-dialog.png?fit=max\&auto=format\&n=m5iWPkGmGTv3i5YV\&q=85\&s=c79aa060e3389150df50c1769b4936c0)

**2. Open APIs & Services > Enabled APIs & services.**

![Animation showing navigation to APIs and Services in Google Cloud Console](https://mintcdn.com/mainwp/m5iWPkGmGTv3i5YV/images/add-ons/ga-apis-services-nav.gif?s=e60ff1e57ff409d616d6886943808404)

**3. Enable the required APIs.**

Enable:

1. **Google Analytics Admin API**
2. **Google Analytics API**
3. **Google Analytics Data API**

![Google Cloud API Library showing required APIs to enable](https://mintcdn.com/mainwp/m5iWPkGmGTv3i5YV/images/add-ons/ga-api-library-apis.png?fit=max\&auto=format\&n=m5iWPkGmGTv3i5YV\&q=85\&s=2264c9d74134370213681c294fa7b71f)

![Animation showing how to search and enable APIs in Google Cloud](https://mintcdn.com/mainwp/m5iWPkGmGTv3i5YV/images/add-ons/ga-enable-api.gif?s=89c9a3c02dc449d554ab97ac1b265196)

**Step 2 - Create a Service Account and JSON key**

1. In **APIs & Services**, click **+ Create credentials** and select **Service Account**.
2. Give it a name and click **Done**.
3. Open the new Service Account, then go to the **KEYS** tab.
4. Click **Add Key > Create new key > JSON > Create**.
5. A JSON file will download automatically.

![Animation showing Service Account creation in Google Cloud Console](https://mintcdn.com/mainwp/m5iWPkGmGTv3i5YV/images/add-ons/ga-service-account-create.gif?s=4ab91af27817c96f830d3929a4136406)

![Animation showing how to create and download a JSON key for Service Account](https://mintcdn.com/mainwp/m5iWPkGmGTv3i5YV/images/add-ons/ga-json-key-download.gif?s=585833b1ebbaf38c9bd7be82c0f0dce8)

**Step 3 - Add the Service Account as Viewer in Google Analytics**

The Service Account can be added as a Viewer to the entire Google Analytics account (all properties) or to specific GA4 properties.

**1. Go to your Google Analytics Dashboard and open Admin.**

Go to [Google Analytics Dashboard](https://analytics.google.com/) and open Admin settings.

**2. Choose account-level or property-level access.**

![Google Analytics Admin settings showing account and property access options](https://mintcdn.com/mainwp/m5iWPkGmGTv3i5YV/images/add-ons/ga-admin-access-settings.png?fit=max\&auto=format\&n=m5iWPkGmGTv3i5YV\&q=85\&s=2a66f582e85b0ae3eda06dac467dee3b)

**3. Click Add users.**

![Google Analytics Access Management with Add users button](https://mintcdn.com/mainwp/m5iWPkGmGTv3i5YV/images/add-ons/ga-add-users-button.png?fit=max\&auto=format\&n=m5iWPkGmGTv3i5YV\&q=85\&s=c4dc3c164ed8761a5abce5ef5ec39071)

**4. Copy the Service Account email from Google Cloud Console.**

![Google Cloud Console Credentials page showing Service Account email](https://mintcdn.com/mainwp/m5iWPkGmGTv3i5YV/images/add-ons/ga-service-account-email.png?fit=max\&auto=format\&n=m5iWPkGmGTv3i5YV\&q=85\&s=e8167add3f44bc6757ade09077e4e99b)

**5. Paste the email, set role to Viewer, and click Add.**

![Google Analytics Add users form with email field and Viewer role](https://mintcdn.com/mainwp/m5iWPkGmGTv3i5YV/images/add-ons/ga-add-users-form.png?fit=max\&auto=format\&n=m5iWPkGmGTv3i5YV\&q=85\&s=ad4dc1b11ffe6d0d170da880d218e345)

If you added property-level access, repeat for each GA4 property you want to use.

**Step 4 - Connect the JSON key in MainWP**

1. In your MainWP Dashboard, go to **MainWP > Add-ons > Google Analytics > Add Account > Import JSON File**.
2. Upload the JSON key file and click **Connect Account**.
3. The account will appear under **Manage Accounts** in **Accounts by JSON**.

![MainWP Google Analytics Add Account page with JSON file upload](https://mintcdn.com/mainwp/0ngAbmgMtzBUDiO6/images/add-ons/import-json.png?fit=max\&auto=format\&n=0ngAbmgMtzBUDiO6\&q=85\&s=87221e5030fcad16ea1bbb875b5a9e2e)

**Important Notes**

* The Google Analytics Extension does not insert Google Analytics tracking code on child sites.
* Add the tracking code manually or by using a third-party plugin.

## Assigning sites from your Google Account to Child Sites in your MainWP Dashboard

The add-on automatically assigns properties to child sites based on URL matching. You can also assign properties manually:

**1. Go to MainWP > Sites > Manage Sites.**

![Animation showing navigation to Manage Sites page](https://mintcdn.com/mainwp/m5iWPkGmGTv3i5YV/images/add-ons/ga-manage-sites-nav.gif?s=5172cb99ed70393632eaf31ec134480f)

**2. Open the child site Settings page.**

Locate the site and click its name to open Settings.

**3. Select the matching Google Analytics property.**

Find the **Google Analytics** section and choose the **Google Analytics property**.

**4. Click Save Settings.**

## Google Analytics Visitor Data

After you connect your Google Analytics account and assign GA4 properties to child sites, you can view data on **MainWP > Add-ons > Google Analytics > Visitor Data**.

![Animation showing Google Analytics Visitor Data page with analytics widgets](https://mintcdn.com/mainwp/prJFyo89l1sl-7Fz/images/add-ons/ga-visitor-data-page.gif?s=8c0e5a95468a12231a06c363ca1c8383)

You can enable or disable widgets in [Page Settings](https://docs.mainwp.com/getting-started/mainwp-user-interface.md), and rearrange them as needed.

![Animation showing how to rearrange widgets in Page Settings](https://mintcdn.com/mainwp/prJFyo89l1sl-7Fz/images/add-ons/ga-widget-rearrange.gif?s=31b38a8d40066d67487cbfd9f0d89076)

To change the child site, select it from the site dropdown.

![Animation showing Child Site selection dropdown for analytics data](https://mintcdn.com/mainwp/prJFyo89l1sl-7Fz/images/add-ons/ga-site-dropdown.gif?s=990fb6255acee37ccd4cd6bc4b5c6009)

## Widgets

A Google Analytics widget is available on the MainWP Overview page and on each individual child site Overview page.

As always, widgets can be enabled or disabled in [Page Settings](https://docs.mainwp.com/getting-started/mainwp-user-interface.md), and they can be rearranged as needed.

![Google Analytics widget on the Overview page displaying visitor statistics](https://mintcdn.com/mainwp/0ngAbmgMtzBUDiO6/images/add-ons/ga-widget.png?fit=max\&auto=format\&n=0ngAbmgMtzBUDiO6\&q=85\&s=a65d5bd4243cd16cde5bef6a54e388ed)

## Settings & Data Refresh

* **Graphs display interval**: Choose **Week** or **Month**
* **Fetch Google Analytics data automatically**: Enable scheduled data refresh
* **Auto fetch GA data frequency**: Set how often automatic refresh runs
* **Save Settings**: Save your interval and schedule preferences
* **Refresh Data**: Trigger an immediate data refresh

If automatic fetching is disabled, visiting MainWP Dashboard pages does not refresh the analytics data. Use **Refresh Data** when you need fresh figures, or enable automatic fetching for scheduled refreshes.

## MainWP Abilities

The Abilities-enabled Google Analytics build registers nine abilities in the `mainwp-google-analytics` category. Use them to read connections and cached properties, manage site mappings and refresh settings, read cached aggregate analytics, and request background refreshes.

The abilities require WordPress 6.9 or later on the MainWP Dashboard site, MainWP Dashboard with Abilities API support, and a Google Analytics build that registers them. Authenticate with a WordPress Application Password. Add-on and site permissions still apply. Mapping changes, refresh-policy changes, and refresh requests require a preview token before confirmation.

See [Google Analytics Abilities](https://docs.mainwp.com/api-reference/abilities-api/google-analytics.md) for discovery, permissions, request examples, response fields, and retry handling. Read abilities return stored Dashboard data; request and track a refresh when you need new data from Google.

## Troubleshooting

### Cannot add the encryption key to `wp-config.php`

If you see this message:

> MainWP Google Analytics could not add its encryption key to wp-config.php.

The add-on could not safely write its encryption key to the MainWP Dashboard site's `wp-config.php` file. This is separate from the Google Service Account JSON key. File mode `0644` does not always allow the update: only the file owner has write access, so the update fails when PHP runs as a different user. File or directory ownership and other server security controls can also prevent a safe update.

Before generating a key, check whether this Dashboard previously used `MAINWP_GA_ENCRYPTION_KEY`. If it did, restore the original definition from your secure configuration backup. A new key cannot decrypt credentials saved with the previous key. Follow [Recover an existing encryption key](#recover-an-existing-encryption-key) if the notice says saved Google credentials cannot be read.

For a Dashboard that has never used an encryption key and has no credentials saved under an older key, add the key manually:

**1. Back up wp-config.php.**

Create a current backup before editing the file.

**2. Generate a secure key.**

Run this command in your server terminal:

```bash theme={null}
openssl rand -hex 32
```

The command returns a 64-character hexadecimal key. Do not use an online key generator.

**3. Add the encryption-key definition.**

Edit the active `wp-config.php` file and add the following line before the line that loads `wp-settings.php`:

```php theme={null}
define( 'MAINWP_GA_ENCRYPTION_KEY', 'PASTE_THE_64_CHARACTER_KEY_HERE' );
```

Replace `PASTE_THE_64_CHARACTER_KEY_HERE` with the key generated in the previous step.

**4. Save the file and reload MainWP Dashboard.**

The warning should clear after the add-on detects the valid key. Do not change or remove the key after it is in use, because existing encrypted credentials may become unavailable.

> [!WARNING]
>
> Do not make `wp-config.php` world-writable or grant PHP permission to change file ownership. If you cannot edit the file safely through your hosting control panel or server account, ask your hosting provider or server administrator to add the definition.

A file ending in `.mainwp-lock` may be created while the add-on coordinates an automatic update. It is a lock file, not the cause of the warning and not a replacement for `wp-config.php`. Add the definition to the active `wp-config.php` file.

If Google Search Console shows a similar warning, follow the instructions in the [Google Search Console troubleshooting section](https://docs.mainwp.com/add-ons/analytics/google-search-console-extension.md#cannot-update-wp-configphp-automatically) and generate a separate key for its constant.

### Recover an existing encryption key

If the Add-on finds saved Google credentials but no encryption key in `wp-config.php`, it keeps those credentials unavailable instead of replacing the key. Back up the current configuration before making changes.

* **The original key is available:** Restore this site's previous `MAINWP_GA_ENCRYPTION_KEY` definition from your secure backup. Place it above the line that loads `wp-settings.php`, keeping exactly one definition. Reload MainWP Dashboard.
* **The original key is lost:** Go to **Google Analytics > Manage Accounts** and use **Remove Account** for every Google account. Then connect each account again from **Add Account**. The Add-on creates a new key once no credentials saved under the old key remain. Removing accounts requires reconnecting them; review the site assignments afterward.
* **The defined key is invalid:** Correct the definition using the original valid key. Generating a different key does not recover existing encrypted credentials.

Keep the encryption key in the Dashboard's secure configuration backups. It is separate from the MainWP Bridge site secret and Google's Service Account JSON key. **Reset Now** repairs the Bridge site secret; it does not recover `MAINWP_GA_ENCRYPTION_KEY`.

### Configuration rollback failed

If the notice says the Add-on could not safely restore `wp-config.php` after a failed update, automatic retries have stopped. Restore the file from a known-good backup, then ask your hosting provider to check disk space, permissions, ACLs, and the server security context.

If no backup is available, have your hosting provider or server administrator inspect the active file before retrying. Keep exactly one encryption-key definition. Restore the previous key when one was already in use; otherwise follow the [initial key setup](#cannot-add-the-encryption-key-to-wp-config-php). Do not generate a replacement for credentials encrypted with a lost key; use the account-removal and reconnection procedure above.

### Sign In with Google buttons are disabled / "Google OAuth requires the WordPress REST API" notice

The extension performs a pre-flight check on your Dashboard's WordPress REST API root (`/wp-json/`) before any Google OAuth action. When the REST API is unreachable, the **Sign In with Google**, **Continue**, **Confirm**, **Reconnect Account**, and refresh buttons are disabled, and a red notice appears on the Add Account and Manage Accounts pages.

* See [WordPress REST API does not respond](https://docs.mainwp.com/troubleshooting/wordpress-rest-api-does-not-respond.md) for steps to restore access (permalinks, security plugins, server rules).
* If HTTP basic auth protects your MainWP Dashboard, **Sign In with Google** can fail because MainWP Bridge cannot complete the initial pairing or re-registration check.
* If you need to keep the REST API restricted, use **Import JSON File** instead — the Service Account flow does not require `/wp-json/` to be public.

### Sign In with Google shows `site secret not found`

* This error usually means the default WordPress REST API endpoint at `/wp-json/` is blocked, disabled, filtered, or behind authentication.
* Make sure your MainWP Dashboard allows access to `/wp-json/`.

### Corrupted or missing site secret (Reset Now)

If the site secret used to authenticate with MainWP Bridge becomes corrupted or goes missing, the extension shows the following notice on its pages:

> The lost secret for the MainWP Google Analytics Extension is corrupted. You need to recover it to be able to use the extension.

Click **Reset Now** in the notice to regenerate the site secret. After the reset completes, reconnect any affected Sign In accounts from **MainWP > Add-ons > Google Analytics > Manage Accounts** using **Reconnect Account**.

### Sign-in account needs verification/reconnection

* Go to **MainWP > Add-ons > Google Analytics > Manage Accounts**
* For disconnected Sign In accounts, click **Reconnect Account**
* Use **Refresh Data** after reconnecting

### OAuth accounts repeatedly require re-verification or Pro Reports miss Google Analytics data

Sign In with Google accounts use OAuth tokens that must be refreshed regularly. The MainWP Google Analytics Extension includes a token refresh cron job that runs hourly and a data refresh cron job that runs every 5 minutes. If WP-Cron does not run for an extended period, the token refresh can be missed. When token refresh fails, the account can be marked as needing re-verification, and Pro Reports may generate scheduled reports without Google Analytics data.

This can happen on low-traffic MainWP Dashboard sites, cached sites, or hosting environments where loopback requests are blocked. An uptime monitor that only pings the homepage may not trigger WP-Cron if the homepage is served from cache.

To keep OAuth accounts connected:

1. Update the MainWP Google Analytics Extension to the latest version.
2. Make sure scheduled tasks are running on the MainWP Dashboard site.
3. Make sure WP-Cron is triggered reliably every 5 to 15 minutes.

The simplest fix is to keep WP-Cron enabled and trigger it directly. If you can add one server cron job, use:

```bash theme={null}
*/5 * * * * wget -O /dev/null https://yourdashboard.com/wp-cron.php?doing_wp_cron > /dev/null 2>&1
```

If you cannot configure a server cron job, configure your uptime monitor to ping the WP-Cron URL directly instead of the homepage:

```text theme={null}
https://yourdashboard.com/wp-cron.php?doing_wp_cron
```

Advanced users can disable WP-Cron and configure individual cron jobs manually, but that is usually not necessary for this issue. See [Disable WP-Cron](https://docs.mainwp.com/customization/disable-wp-cron.md) only if you intentionally manage MainWP schedules through server-side cron jobs.

After cron is running reliably, reconnect any affected accounts once from **MainWP > Add-ons > Google Analytics > Manage Accounts** using **Reconnect Account**, then click **Refresh Data** and generate a test Pro Report.

If accounts still require re-verification after cron is stable, check for a corrupted or missing site secret, a changed Dashboard domain after migration, token data corruption, network/API errors reaching MainWP Bridge, or a temporary MainWP Bridge service issue.

### Service Account key disabled or rotated

* Re-enable the Service Account in Google Cloud Console
* Create and download a new JSON key from **Keys > Add Key > Create new key**
* Upload the new key in **MainWP > Add-ons > Google Analytics > Add Account > Import JSON File**

### Required PHP functions missing

* Google Analytics requires `bccomp`, `putenv`, and `getmypid`.
* If Google Analytics data is unavailable, review [Required PHP Functions for MainWP](https://docs.mainwp.com/advanced/miscellaneous/required-php-functions-for-mainwp.md) to check whether these functions are disabled on your server.

![Google Cloud Console showing disabled Service Account status](https://mintcdn.com/mainwp/m5iWPkGmGTv3i5YV/images/add-ons/ga-service-account-disabled.png?fit=max\&auto=format\&n=m5iWPkGmGTv3i5YV\&q=85\&s=fb8a8188095931915336a4cf440a1752)

![Animation showing how to create a new JSON key from Service Account](https://mintcdn.com/mainwp/m5iWPkGmGTv3i5YV/images/add-ons/ga-new-json-key.gif?s=46b06acaf54e44ccbcdc56e5ae3fb79f)

***

## Related Resources

* [Google Analytics Abilities](https://docs.mainwp.com/api-reference/abilities-api/google-analytics.md) - Read cached analytics, manage mappings, and track background refreshes
* [Database Health Check](https://docs.mainwp.com/dashboard/overview/mainwp-database-health-check.md) - Check the Add-on's registered account, site-assignment, and cached-statistics tables
* [Analytics Add-ons](https://docs.mainwp.com/add-ons/analytics.md) - Browse all analytics integrations
* [Pro Reports Extension](https://docs.mainwp.com/add-ons/agency/pro-reports-extension-overview.md) - Include analytics data in reports
* [Available Pro Reports Tokens](https://docs.mainwp.com/add-ons/agency/available-pro-reports-tokens.md) - Google Analytics tokens
* [MainWP Bridge Privacy Policy](https://mainwp.com/mainwp-bridge-privacy-policy) - Privacy details for Bridge-based sign in


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.