=== Tagsmith ===
Contributors: shivaat
Tags: google analytics, ga4, analytics, dashboard, statistics
Requires at least: 6.7
Tested up to: 7.1
Requires PHP: 8.1
Stable tag: 2.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

See Google Analytics 4 reports inside WordPress: a clear dashboard, per-post stats and Search Console. Read-only Google access. No nags.

== Description ==

**Tagsmith shows your Google Analytics 4 reports inside WordPress.** See your visitors, top pages, traffic sources, Search Console queries and the stats of each post. It also adds the Google tag to your site, following your consent settings. Google access is read-only.

If you use Microsoft Clarity, Tagsmith can add its tag under the same consent rules and show its behavior insights.

= Our pledges =

* **No nags.** No upgrade prompts and no admin notices outside the plugin's own screens. The one exception is a notice that the plugin needs a newer PHP or WordPress, shown only to people who manage plugins.
* **No bundled plugins.** Tagsmith never installs or activates anything else.
* **No telemetry.** The plugin sends us no usage data. The sign-in relay sees your site address, your IP address and the email of the Google account you sign in with, only while you connect or refresh tokens, and keeps none of it on disk.
* **Free stays free.** Nothing in this plugin will be locked or removed later.
* **Read-only access.** Tagsmith can only view your Google data.
* **Clean uninstall.** Deleting the plugin removes its settings, saved reports, Clarity snapshots and tokens from the database and asks Google to revoke its access (you can turn this off in Settings, Advanced). If your site cannot reach Google then, or is a copy whose address changed (Tagsmith does not ask Google to revoke), remove the access at myaccount.google.com/permissions. On a site with an external object cache, cached report copies expire by themselves within a week.

= Features =

* **GA4 tracking.** Pick your property and web stream to fill in the Measurement ID, or paste a `G-` ID to skip sign-in.
* **Dashboard.** Seven tabs and a widget on the wp-admin home screen.
* **Per-post stats.** A "Views (28 days)" column in the Posts list and a block editor panel. Both need pretty permalinks.
* **Health check.** Finds duplicate tags and other mismatches with Google.

Google Analytics, Search Console and the Google tag are trademarks of Google LLC; Microsoft Clarity is a Microsoft product. Tagsmith is not made or endorsed by either.

== External services ==

Tagsmith contacts these services, and only for the features you turn on.

**Google APIs (your site to Google).** When you connect, your site calls Google directly to read your reports: `analyticsdata.googleapis.com` (Data API), `analyticsadmin.googleapis.com` (Admin API: your properties and web streams), `searchconsole.googleapis.com` (only if you turn on Search Console) and `oauth2.googleapis.com` (to revoke access, and to sign in and refresh it if you use your own Google client). Your site sends its access token and the report it wants, and your analytics data comes straight back from Google, never through the plugin author. Google's own sign-in page (`accounts.google.com`) opens in your browser when you connect.
When you are connected and the health checks run (Settings, Health, and the last setup step), your site also sends one `HEAD` request to `analyticsdata.googleapis.com` and only notes whether any answer comes back. It is not sent in tracking-only mode. It carries no token, report request or analytics data. Google sees your server's IP address and WordPress's standard User-Agent, which names your WordPress version and site address.

* Google Analytics: https://analytics.google.com/
* Google Search Console: https://search.google.com/search-console
* Google Terms: https://policies.google.com/terms
* Google Privacy: https://policies.google.com/privacy

**The Tagsmith sign-in relay (`connect.shivaatripathi.com`).** Google does not let a plugin ship the secret that sign-in needs, so a relay run by the plugin author holds it. Your browser is sent to it when you click "Connect with Google", and your site calls it directly to refresh its access token: about once an hour while you use the reports, and when a health check runs (the plugin's, or WordPress's Site Health). The relay passes the sign-in code and tokens between Google and your site. It does not store or log tokens and never sees your analytics data. It sees your site address, your IP address (for rate limiting) and the email of the Google account (passed straight back to your site), and keeps none of it on disk. It is served through Cloudflare, which sees requests like any CDN. It is not contacted in tracking-only mode or with your own Google client. Google shows its "unverified app" screen at sign-in while its review of the app is pending.

* Sign-in relay: https://shivaatripathi.com/tagsmith/
* Relay privacy: https://shivaatripathi.com/tagsmith/privacy/
* Relay terms: https://shivaatripathi.com/tagsmith/terms/

**Google's tag (your visitors to Google).** When tracking is on, your visitors' browsers load Google's gtag.js from `www.googletagmanager.com` and send page views and events to Google Analytics. In Advanced mode (the default) the tag loads for every visitor. Visitors whose default is "not agreed" (by default those in the EEA, the UK and Switzerland) send only cookieless pings until they agree, and Google says nothing is stored on their device. In Basic mode nothing is sent to Google before a visitor agrees. Excluded roles and non-production sites load nothing.

* Google Analytics: https://analytics.google.com/
* Google Terms: https://policies.google.com/terms
* Google Privacy: https://policies.google.com/privacy

**Microsoft Clarity (only if you turn it on).** Its tag (your visitors to Microsoft): visitors' browsers load Clarity's script from `www.clarity.ms` and send Microsoft how they use your pages (pages viewed, clicks, scrolling and mouse movements, which Clarity turns into heatmaps and recordings), with device, browser and approximate location. Consent, excluded roles and staging rules apply as for the Google tag. With WordPress context tags on (the default), recordings also carry the page type, post type, first category slug, an author number (the author's user ID) and whether the visitor is logged in: no names, emails or other personal data. Its Data Export API (your site to Microsoft), only if you save a Data Export token: once a day your site asks `www.clarity.ms` for your project's behavior metrics for the last one to three days (two calls; "Sync now" can ask again at most once an hour, and never more than 8 calls a day). Clarity sends back aggregated numbers for the whole site and per page: Clarity sessions, bot sessions, scroll depth, active time, and how many sessions had rage clicks, dead clicks, quick backs, excessive scrolling, JavaScript errors or click errors. Tagsmith keeps these daily snapshots, for your own site's pages only, in your WordPress database for 120 days. The token is stored encrypted and never shown again; removing it stops the calls.

* Microsoft Clarity: https://clarity.microsoft.com
* Clarity Terms: https://clarity.microsoft.com/terms
* Microsoft Privacy: https://privacy.microsoft.com/privacystatement

Nothing else is added to your front end.

== Installation ==

1. Go to Plugins, Add New, then install and activate Tagsmith.
2. Go to Tagsmith, Settings. The setup wizard starts.
3. Read the pledges and data disclosure, then choose how to connect:
    * **Connect with Google** to see reports in WordPress (recommended), or
    * **Add the tracking code only** to paste a `G-` Measurement ID, for tracking only.
4. If you connected, choose your GA4 property and web stream, and optionally turn on Search Console.
5. Review tracking and privacy (excluded roles, Consent Mode).
6. Open Tagsmith, Dashboard.

== Frequently Asked Questions ==

= Can I use my own Google OAuth client? =

Yes: Settings, Advanced, "Use my own Google client", which shows the redirect URI to register. Publish your consent screen "In production", or Google disconnects you every 7 days.

= Why don't the numbers match Google Analytics exactly? =

Cached reports (use Refresh), different time zones in WordPress and GA4, or a second tag from a theme or plugin (Health checks for it).

= How does consent work? =

Tagsmith uses Google Consent Mode v2 and follows your consent banner (it shows none itself). Clarity follows the same setting, with three values:

* **Advanced** (default): the tag loads for everyone, but by default in the EEA, UK and Switzerland it starts with consent denied until the visitor agrees.
* **Basic**: the tag loads only after the visitor agrees. A banner that assumes consent until the visitor declines counts as agreed. This needs a banner that supports the WP Consent API or calls `window.tagsmithGrant()`.
* **Off**: no consent signals are sent.

= Does it work with Microsoft Clarity? =

Yes. Turn it on and enter your Project ID in Settings, Tracking. If Microsoft's own Clarity plugin is active, turn it off, or the tag loads twice.

= Where is the source code for the JavaScript? =

`build` is compiled from `assets/src`. To rebuild it, use Node 22 and run `npm ci && npm run build` in the plugin folder.

= What is the demo folder? =

The `demo` folder holds sample data for the Live Preview.

== Screenshots ==

1. Your GA4 reports inside wp-admin: KPIs, trends, top pages and channels.
2. See each post's views, channels and search queries while you write.
3. Spot pages that frustrate visitors: rage clicks, dead clicks, scroll depth.
4. See which Google searches bring people to your site.
5. Find duplicate tags and other reasons your numbers don't match Google.
6. Our pledges and exactly what data leaves your site, before you connect.
7. Consent Mode, excluded roles and staging rules, with sensible defaults.

The screenshots use sample data.

== Changelog ==

= 2.0.0 =
* First release.
