=== 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.1.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**: visitors, top pages, traffic sources, Search Console queries and per-post stats. It also adds the Google tag, following your consent settings.

It can also add Microsoft Clarity and the ad pixels of Meta, Google Ads, TikTok, LinkedIn, Microsoft Advertising, Pinterest, Snap and X. All stay off until you switch them on and enter an ID, and follow your consent settings.

= Our pledges =

* **No nags.** No upgrade prompts and no admin notices outside the plugin's own screens, except one telling people who manage plugins that it needs a newer PHP or WordPress.
* **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. 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.
* **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, only for features you turn on.

**Google APIs (your site to Google).** When you connect, your site calls Google directly to read your [Google Analytics](https://analytics.google.com/) reports: `analyticsdata.googleapis.com` (reports), `analyticsadmin.googleapis.com` (your properties and web streams), `searchconsole.googleapis.com` (only if you turn on [Search Console](https://search.google.com/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 the data comes straight back from Google, never through the plugin author. Google's 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, with no token, report request or analytics data. It is not sent in tracking-only mode. Google sees your server's IP address and WordPress's User-Agent (your WordPress version and site address).

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

**The Tagsmith [sign-in relay](https://shivaatripathi.com/tagsmith) (`connect.shivaatripathi.com`).** A relay run by the plugin author holds the sign-in secret Google does not let a plugin ship. 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). It passes the sign-in code and tokens through without storing or logging them 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, plus `generate_lead` (form plugin and form ID) and `contact` (kind of link) events when an ad pixel is on and those events are left on. 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. A banner that assumes consent until the visitor declines counts as agreed. Excluded roles and non-production sites load nothing, pixels included. [Google Ads](https://ads.google.com), if on, shares this gtag.js, sends page views and, as conversions you create, form leads and contact taps, waits for marketing consent like the other pixels (in Basic mode with the Google tag set up, also for its grant) and uses `www.googleadservices.com`, `googleads.g.doubleclick.net` and `www.google.com`.

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

**[Microsoft Clarity](https://clarity.microsoft.com) (only if you turn it on).** Visitors' browsers load Clarity's script from `www.clarity.ms` and send Microsoft how they use your pages (clicks, scrolling and mouse movements), with device, browser and approximate location, under the Google tag's consent, role and staging rules. WordPress context tags (on by default) add the page type, post type, first category, the author's user ID and login state, never names or emails. With a saved Data Export token, your site also asks `www.clarity.ms` once a day for aggregated behavior metrics (at most 8 calls a day) and keeps the snapshots for 120 days.

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

**Ad pixels (only the ones you turn on).** Each platform is off until you switch it on and enter its ID in Ads & pixels. Browsers then load its script from its listed hosts and send it page views and the events named in its entry. A form lead is the event only; a contact tap is at most the kind of link, never the number or address. Its script also reads the page address with its query string, the referrer, the IP address and browser details, and sets cookies. Search terms that look like an email address or phone number are dropped, and Tagsmith adds no names, emails or form entries. No other pixel loads until the visitor agrees to marketing cookies where your consent setting asks for it. Google Ads shares the Google tag's gtag.js, as above. Product names belong to their owners, with no affiliation.

**[Meta Pixel](https://www.facebook.com/business/tools/meta-pixel).** Page views, content views (title, category), searches (term), form leads, contact taps. `connect.facebook.net`, `www.facebook.com`, `www.instagram.com`.

* Terms: https://www.facebook.com/legal/technology_terms
* Privacy: https://www.facebook.com/privacy/policy/

**[TikTok Pixel](https://ads.tiktok.com/resources/help/article/tiktok-pixel).** Page views, content views (title, category), searches (term), form leads, contact taps. `analytics.tiktok.com`, `analytics-ipv6.tiktokw.us`, `analytics.pangle-ads.com`.

* Terms: https://ads.tiktok.com/i18n/official/policy/business-products-terms
* Privacy: https://www.tiktok.com/legal/page/row/privacy-policy/en

**[LinkedIn Insight Tag](https://business.linkedin.com/advertise/ads/insight-tag).** Page views, and form leads and contact taps as conversions you create. `snap.licdn.com`, `px.ads.linkedin.com`.

* Terms: https://www.linkedin.com/legal/user-agreement
* Privacy: https://www.linkedin.com/legal/privacy-policy

**[Microsoft Advertising UET tag](https://ads.microsoft.com).** Page views, content views (title, category), searches (term), form leads, contact taps (the kind of link). `bat.bing.com`, `bat.bing.net`.

* Terms: https://about.ads.microsoft.com/en/resources/policies/microsoft-advertising-agreement
* Privacy: https://privacy.microsoft.com/privacystatement

**[Pinterest Tag](https://business.pinterest.com).** Page views, content views (the visit only), searches (term), form leads, contact taps. `s.pinimg.com`, `ct.pinterest.com`.

* Terms: https://policy.pinterest.com/en/terms-of-service
* Privacy: https://policy.pinterest.com/en/privacy-policy

**[Snap Pixel](https://businesshelp.snapchat.com/s/article/snap-pixel-about).** Page views, content views (title, category), searches (term), form leads; no contact event. `sc-static.net`, `tr.snapchat.com`, `tr6.snapchat.com`, `tr-shadow.snapchat.com`.

* Terms: https://www.snap.com/terms
* Privacy: https://values.snap.com/privacy/privacy-policy

**[X Pixel](https://business.x.com).** Page views, and form leads and contact taps as conversions you create. `static.ads-twitter.com`, `analytics.twitter.com`, `t.co`, `ads-twitter.com`, `ads-api.twitter.com`.

* Terms: https://x.com/en/tos
* Privacy: https://x.com/en/privacy

== 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 ==

= How does consent work? =

Tagsmith uses Google Consent Mode v2 and follows the choices made in your consent banner (it shows none). 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 (an opt-out banner counts as agreed). This needs a banner that supports the WP Consent API, or one that calls `window.tagsmithGrant()`.
* **Off**: no consent signals are sent.

= How do the ad pixels work with consent? =

In Advanced mode they wait for marketing consent from visitors whose default is "not agreed", in Basic mode from everyone; in Off mode they load for everyone. Without a WP Consent API banner or Google Consent Mode (`ad_storage`), a visitor who has to agree never triggers a pixel. Where visitors must agree, a banner that decides only in the browser (CookieYes) loses leads from forms that send visitors to another page. Google Ads waits the same way and, in Basic mode with the Google tag set up, also for its grant.

= 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 in wp-admin: what changed, key numbers, trends.
2. A post's views, channels and searches, while you write.
3. Rage clicks, dead clicks and scroll depth, by page.
4. Google searches that bring people to your site.
5. Duplicate tags and other reasons your numbers differ.
6. Our pledges and what data leaves your site.
7. Consent Mode, excluded roles and staging rules.
8. Ad pixels: switch on platforms, choose their events.

The screenshots use sample data.

== Changelog ==

= 2.1.0 =
* New: ad pixels for Meta, Google Ads, TikTok, LinkedIn, Microsoft Advertising, Pinterest, Snap and X, set up in the new Ads & pixels tab and off until you switch one on.
* New: pixels wait for marketing consent where your consent setting asks for it; Google Ads also waits for the Google tag's grant in Basic mode.
* New: form leads from WPForms, Gravity Forms, Fluent Forms and Elementor Pro, plus a `tagsmith_pixel_lead` action for other forms.
* New: Health finds pixels your theme or another plugin also adds, and a preview shows what the pixels would send, without sending it.
* New: a "What changed" strip on the Overview, with KPI tiles and tables compared with the previous period.
* New: the block editor panel and the home screen widget say what moved.
* Changed: Health says "Not in use" for features you switched off.
* Changed: numbers follow your site's language; settings and dashboard fit down to 320px wide.
* Changed: the Advanced tab is now "Sign-in & data", and every settings form ends with one unsaved-changes bar.
* Fixed: reports asked for before Google is connected answer 409, not 401, which a security plugin could read as a failed login.

= 2.0.0 =
* First release.
