=== Altima Multisite Analytics ===
Contributors: altimaweb
Tags: google analytics, ga4, search console, client reports, agency
Requires at least: 6.0
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.5.1
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

GA4 and Search Console for every site you manage, in one WordPress dashboard, with plain-English insights and emailed client reports.

== Description ==

Stop logging in to ten WordPress admins or clicking through Google Analytics property by property. Click **Sign in with Google**, and every GA4 property your Google account can already see appears on one screen. No Google Cloud setup, no API keys.

**Overview of all sites**

* Totals across your portfolio: visitors, sessions, key events, Google search clicks and revenue.
* One chart of visitors across all your sites, compared with the previous period.
* A sortable table of every site: visitors and change, engagement, key events, a trend sparkline, a 0–100 health score and the single most important insight.
* "Needs attention" and "Wins" feeds that surface the critical changes across all sites first.
* Pin your most important sites to the top; hide the ones you do not need. Each user's choice is their own.
* Filter by client or group. Export to CSV.

**A full analytics portal for each site**

Open any site and get its own portal: a header with live visitors, a side menu, and a section for every question.

* **Overview:** clickable number tiles with trend lines (visitors, sessions, page views, views per session, engagement, session time, bounce rate, key events, revenue, search clicks). Click a tile to chart it against the previous period or the same period last year.
* **Traffic sources:** a channel donut, channel performance, every source and medium, and referring websites, each with its share.
* **Pages & events:** top content with page titles, landing pages, and events with key events marked.
* **Locations:** a world map and a US state map shaded by visitors or sessions, plus country, state and city tables. The maps are drawn inside the plugin; nothing is loaded from other sites.
* **Devices & tech:** devices, new vs returning visitors, browsers and operating systems.
* **When they visit:** a day-by-hour heatmap with the busiest day, busiest time, quietest day and weekend share, so you can plan posts, emails and ads.
* **Google search:** clicks, impressions, click-through rate, average position, top queries, pages in search and devices from Search Console, matched to each site automatically.
* **Speed:** performance score, real-visitor Core Web Vitals (LCP, INP, CLS), lab metrics and Google's biggest suggested fixes, for mobile and desktop.
* **Insights:** what changed, why it matters and what to do next.
* Switch sites from a dropdown or step through them with previous / next. Custom date ranges and year-over-year comparison.

**Reports and shortcuts**

* **Client reports by email:** a branded, plain-English report for each site, emailed to its client automatically every month or week, plus one-click printable reports.
* **WP Dashboard widget** with every site at a glance, and an **Analytics** item in the front-end admin bar showing the current page's views, visitors and Google search performance.

**Insights for every site**

Rules written to say what changed, why it matters and what to do next, with volume guards so small numbers never raise false alarms:

* No data recorded for the last few days (the tag was probably removed)
* Visitors, engagement, key events or revenue up or down
* Key events falling while traffic holds (a broken form or checkout)
* Organic search drop, channel gains and losses, over-reliance on one channel
* Pages gaining or losing views
* Mobile visitors engaging much less than desktop
* Bot or spam referrals
* Google search clicks or ranking falling, search terms close to page 1, pages seen in Google but rarely clicked, lost search terms
* Slow pages and failing Core Web Vitals
* Single-day traffic spikes
* No key events configured

Developers can add rules with the `altmsa_insights` filter.

**Built for agencies**

* One-click Sign in with Google. Agencies can instead use a Google service account or their own Google Cloud app.
* Read-only access (analytics.readonly). Secrets are stored encrypted.
* Choose which roles can view the dashboard. Only administrators change settings.
* Weekly email digest of every site, worst first.
* Reports are cached (60 minutes by default) and pre-warmed daily to stay inside Google's quotas. If Google is unavailable the last good numbers are shown with a notice.
* Demo mode with six sample sites so you can explore before connecting.

== Installation ==

1. Plugins → Add New → Upload Plugin, choose the ZIP, activate.
2. Analytics → Settings → **Sign in with Google**, choose the Google account you use for Google Analytics, and allow read-only access.
3. Analytics → Sites: untick any properties you don't want, and give them friendly names and client groups.

Until you connect, Analytics → Dashboard shows demo data so you can look around.

== Frequently Asked Questions ==

= Do I need to install this on every site? =

No. Install it once, on any WordPress site (your agency site is ideal). It reads data from Google Analytics directly, so the client sites do not need anything installed.

= Does it work with Universal Analytics? =

No. Universal Analytics stopped collecting data in 2023. This plugin reads GA4 properties.

= My site is missing from the list =

The Google account you signed in with can't see it. In Google Analytics, ask the property owner to add that account (Admin → Property access management, role Viewer), then click "Refresh property list from Google" on the Sites screen.

= Why does a site show "The service account cannot read this property"? =

In Google Analytics open that property → Admin → Property access management, and add the service-account email (shown in Settings) as a Viewer. Adding it at account level covers every property in the account.

= How fresh are the numbers? =

Reports cover full days up to yesterday and are cached for the time set in Settings. Administrators can click Refresh to fetch fresh data. Realtime visitors update every minute.

== External services ==

This plugin connects to Google to show your Google Analytics data.

* **Google Analytics Data API and Admin API** (analyticsdata.googleapis.com, analyticsadmin.googleapis.com): your site requests reports and the list of properties you can access. [Google Terms](https://policies.google.com/terms), [Google Privacy Policy](https://policies.google.com/privacy).
* **Google sign-in** (accounts.google.com, oauth2.googleapis.com): used when you connect, and to keep the connection active.
* **Google Search Console API** (www.googleapis.com/webmasters/v3): search performance for sites you have access to in Search Console.
* **PageSpeed Insights API** (www.googleapis.com/pagespeedonline): your site's home page address is sent to Google to run the speed test.
* **Altima Web connection service** (connect.altimaweb.com, with a backup at altimaweb.com/wp-json/msa-broker/v1/), used only with "Sign in with Google": it relays the sign-in, because Google requires one registered app, and issues short-lived access tokens. It receives your site's address and name when you connect, and your site's Google refresh token each time a fresh access token is needed. It stores no tokens and no analytics data. [Privacy policy](https://altimaweb.com/privacy-policy/).

The "Service account" and "Your own Google Cloud app" methods do not use the Altima Web connection service.

== Screenshots ==

1. Every site at a glance: portfolio totals, visitors across all sites over time, and what needs attention or improved.
2. One site's portal: clickable number tiles with trends, the chart, top insights, a world map, traffic sources and more.
3. Locations: a world or US state map shaded by visitors, with country, state and city tables.
4. When visitors come: sessions by weekday and hour, with the busiest day and time.
5. Traffic sources: channels, sources and referring websites, with each one's share.
6. Google search: clicks, impressions, click-through rate and position from Search Console.
7. Insights: what changed, why it matters, and what to do next.
8. Client report: the branded, plain-English email each client receives every month or week.
9. A summary of every site on the WordPress dashboard.
10. Connect in one click with Sign in with Google. No Google Cloud project or API keys needed.

== Changelog ==









= 1.5.1 =
* Google reports now go through the WordPress HTTP API, so the site's proxy settings and HTTP filters apply
* A browser request shares one time budget across all reports; slow properties show the saved numbers and refresh in the background


= 1.5.0 =
* New site portal: dark site header with live visitors, side navigation and clickable number tiles with trend lines that pick what the chart shows
* New Locations section: world map and US state map shaded by visitors or sessions, with country, state and city tables
* New Devices and tech section: device and new-vs-returning donuts, browsers and operating systems
* New When they visit section: day-by-hour heatmap with busiest day, busiest time and weekend share
* Traffic sources section with channel donut, channel performance, sources and referring websites
* Tables now show each row's share with a bar
* All-sites overview adds a combined visitors trend chart
* Maps are drawn locally; nothing is loaded from other sites


= 1.4.0 =
* Renamed to Altima Multisite Analytics (new slug altima-multisite-analytics); settings, site list and Google connection carry over automatically from MultiSite Analytics
* All functions, options and handles now use the altmsa prefix
* Added nonce checks to the Google sign-in return steps
* Site icons are now drawn locally instead of being fetched from Google
* Menu no longer claims a fixed position near the top of the admin menu
* The sign-in relay and uptime monitor moved out of this plugin into a separate service plugin


= 1.3.7 =
* At most 4 report requests to Google at a time per site, well inside Google's per-property limit shared with Site Kit and other tools


= 1.3.6 =
* Slow Google Analytics properties no longer show timeout errors: the dashboard shows the last saved report straight away and fetches a fresh one in the background, where it can wait up to 3 minutes
* Saved reports are kept when the plugin is updated


= 1.3.5 =
* Fixed: busy Google Analytics properties no longer fail with 'cURL error 28: Operation timed out'. Reports for a site are now requested from Google all at once instead of one batch, and the plugin waits up to 60 seconds


= 1.3.4 =
* Fixed: the printable client report no longer starts with a blank page
* Client report emails: engagement changes are shown in percentage points


= 1.3.3 =
* Readme: screenshots, a shorter summary and updated tags for the WordPress.org directory


= 1.3.2 =
* Client reports: a site with no Google Analytics visits in the period is not emailed to the client; the preview explains why and the log records it
* Client reports: '1 time' instead of '1 times'


= 1.3.1 =
* Client reports: chart dates now follow the site's timezone
* Client reports: web addresses with accents or non-English letters are shown readably
* Client reports: a figure that is zero in both periods shows 'no change'


= 1.3.0 =
* New: Client reports. A branded, plain-English report for each site, emailed to its client every month or week: key numbers and changes, a visitors chart, highlights and next steps, top pages, top Google searches and where visitors came from
* Set each site's client email on the Sites screen, with Preview and Send test links; choose frequency, sender name, reply-to and a personal note under Settings
* Reports are sent once per period, in small batches, and retried the next day if sending fails; a log shows what was sent


= 1.2.4 =
* New for the Altima Web sign-in service: an hourly uptime monitor that emails an alert when a sign-in address fails twice in a row, and again when it recovers


= 1.2.3 =
* Sign in with Google now uses a dedicated Altima Web sign-in service (connect.altimaweb.com), with automatic fallback to a backup if it cannot be reached
* Clearer message when the sign-in service is unavailable; saved numbers keep showing


= 1.2.2 =
* Admin scripts now load from a file instead of inline
* Settings and Sites input sanitised on arrival
* Tested with WordPress 7.1 and PHP 8.5
* Passes the WordPress.org Plugin Check


= 1.2.1 =
* Fixed: speed tests now authenticate with the site's Google connection (Google no longer allows anonymous PageSpeed tests)
* Fixed: Google errors are no longer hidden behind Cloudflare 'Bad gateway' pages

= 1.2.0 =
* Search Console: clicks, impressions, CTR, position, top queries and pages, auto-matched per site, plus search insights
* PageSpeed Insights and Core Web Vitals per site (mobile and desktop) with the biggest fixes
* More Analytics: page titles, landing pages, events, new vs returning, cities
* Site view redesigned with tabs; custom date ranges; site icons; Search clicks in the all-sites table
* WP Dashboard widget and front-end admin-bar page stats
* Printable client report
* Optional PageSpeed API key setting

= 1.1.4 =
* Fixed: 'No data recorded' alarm no longer fires on low-traffic sites where quiet days are normal
* Sites with under 50 sessions now show 'Low traffic' instead of an unreliable health score

= 1.1.3 =
* Fixed: Sign in with Google could fail with 'The sign-in expired or was started somewhere else' when the button was triggered twice (prefetch, double-click, second tab) or the host's cache dropped temporary data. Each sign-in is now stored separately for up to an hour

= 1.1.2 =
* Connection service: the Google app ID and secret can now be saved in Analytics -> Settings on altimaweb.com, no wp-config.php edit needed

= 1.1.1 =
* Sign in with Google now checks the sign-in service first and shows a clear message if it is unavailable, instead of a raw error page
* Connection service has a status address for setup checks

= 1.1.0 =
* One-click Sign in with Google: no Google Cloud setup or keys for users
* Built-in connection service, switched on for altimaweb.com with two wp-config lines
* Simpler Settings screen; service account and own-app options moved under Advanced
* Fixed: a cancelled Google sign-in now says so instead of showing a generic error
* External services section added to the readme

= 1.0.0 =
* First release.
