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
Use this Extension To Track:
- Views
- Views by Page
- Users
- Users by Device
- Users by Country
- New Users
- Average Engagement Time
- Sessions by Source
- PHP 8.3 or higher on the Dashboard server when using MainWP Dashboard 6.4 (see System Requirements)
- 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):
Option A: Sign In with Google
- In your MainWP Dashboard, go to MainWP > Add-ons > Google Analytics > Add Account.
- Keep the Sign In with Google tab selected, then click Sign In with Google.
- Complete Google authorization in the popup window.
- In Select Google Analytics Project, choose the account(s) you want to connect, then click Continue.
- In Confirm Google Analytics Connection, review the summary and click Confirm.
- Your account will appear under Manage Accounts in Accounts by Sign In.
- This flow uses MainWP Bridge (
bridge.mainwp.com) for secure authentication. See MainWP Bridge and the 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. Use Import JSON File to connect in the meantime.
Option B: Connect a Service Account (JSON file)
Step 1 - Enable required APIs in Google Cloud ConsoleGo to https://console.cloud.google.com and create a new project (optional).

Open APIs & Services > Enabled APIs & services.

Enable the required APIs.
- Google Analytics Admin API
- Google Analytics API
- Google Analytics Data API


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


Go to your Google Analytics Dashboard and open Admin.
Choose account-level or property-level access.

Click Add users.

Copy the Service Account email from Google Cloud Console.

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

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

- 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:Go to MainWP > Sites > Manage Sites.

Open the child site Settings page.
Select the matching Google Analytics property.
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.


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, and they can be rearranged as needed.
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
MainWP Abilities
The Abilities-enabled Google Analytics build registers nine abilities in themainwp-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 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 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:
Back up wp-config.php.
Generate a secure key.
Add the encryption-key definition.
wp-config.php file and add the following line before the line that loads wp-settings.php:PASTE_THE_64_CHARACTER_KEY_HERE with the key generated in the previous step.Save the file and reload MainWP Dashboard.
.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 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 inwp-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_KEYdefinition from your secure backup. Place it above the line that loadswp-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.
MAINWP_GA_ENCRYPTION_KEY.
Configuration rollback failed
If the notice says the Add-on could not safely restorewp-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. 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 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:- Update the MainWP Google Analytics Extension to the latest version.
- Make sure scheduled tasks are running on the MainWP Dashboard site.
- Make sure WP-Cron is triggered reliably every 5 to 15 minutes.
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, andgetmypid. - If Google Analytics data is unavailable, review Required PHP Functions for MainWP to check whether these functions are disabled on your server.


Related Resources
- Google Analytics Abilities - Read cached analytics, manage mappings, and track background refreshes
- Database Health Check - Check the Add-on’s registered account, site-assignment, and cached-statistics tables
- Analytics Add-ons - Browse all analytics integrations
- Pro Reports Extension - Include analytics data in reports
- Available Pro Reports Tokens - Google Analytics tokens
- MainWP Bridge Privacy Policy - Privacy details for Bridge-based sign in
