=== Pulse Analytics - GA4 Analytics for WordPress & WooCommerce ===
Contributors: smackcoders, premairuthayarajan, fenzik, smackmarketing
Donate link: https://www.smackcoders.com/contact-us.html
Tags: analytics, google analytics, woocommerce, google analytics dashboard, ga4
Requires at least: 6.4
Tested up to: 7.1
Stable tag: 2.0
Requires PHP: 7.4
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Connect any WordPress site to Google Analytics 4 and see traffic, revenue, and customer behavior without ever leaving your dashboard.

== Description ==

**WP Pulse Analytics** brings Google Analytics 4 directly into your WordPress admin, for blogs, business sites, and online stores alike. Instead of logging into a separate Google Analytics account and digging through menus that were never built with regular site owners in mind, you connect your GA4 property once and your traffic starts showing up right where you already work.

Version 2.0 is the biggest release WP Pulse Analytics has ever had. The core dashboard now runs entirely on live GA4 data rather than a separate local event log, and twenty dedicated Pro modules turn that same GA4 connection into real-time visitor tracking, full commerce funnels, form conversion analysis, video engagement, search performance, and a built-in AI assistant that answers plain-English questions about your own site. Everything still lives inside the WordPress admin you already know, powered by the Google Analytics 4 property you already own.

For stores, WP Pulse Analytics goes further. It tracks the full customer journey from landing on the site through checkout, shows exactly where revenue is coming from, and flags where customers are dropping off before they complete a purchase. Affiliate and outbound link clicks are classified and reported automatically, page speed is monitored through Core Web Vitals, and a built-in Ask AI assistant answers plain-English questions about your site's performance without you needing to build a report yourself.

Full setup guides and documentation for every free and Pro feature are available at the [WP Pulse Analytics Documentation](https://www.smackcoders.com/documentation/pulse-analytics?utm_source=wordpress_org&utm_medium=readme&utm_campaign=pulse_analytics_free&utm_content=description_docs_link).

= Highlights =

* Live GA4-powered traffic dashboard — active visitors (real-time), sessions with period comparison, page views with pages/session, average session duration, engagement rate, and new vs. returning visitor split
* Device Type and Browser breakdowns, Top Pages, and Visitor Geography tables
* Real-time visitor tracking, including device and location
* Affiliate and outbound link click tracking, with a dedicated Affiliate Links report
* Automatic form submission tracking for Contact Form 7, Gravity Forms, WPForms, Ninja Forms, and Forminator
* Global admin date picker with custom date ranges across every free report
* Privacy and Consent controls, including PII stripping and consent-gated tracking
* Works with WooCommerce, Easy Digital Downloads, MemberPress, and GiveWP

= Pro Features (all 20, included in WP Pulse Analytics Pro) =

* **Real-Time Visitors** – Live active-user counts, currently viewed pages, and visitor geography, refreshing automatically.
* **Traffic Overview** – Channels, landing pages, source/medium, and AI referral traffic (ChatGPT, Claude, Gemini, Perplexity) in one report.
* **Google Search Console Integration** – Search queries, impressions, click-through rate, and average ranking position inside WordPress.
* **eCommerce Analytics** – A nine-tab WooCommerce report covering revenue, funnel, coupons, refunds, geography, and cart abandonment.
* **Forms Conversion Tracking** – Full view-to-submission funnel and per-form conversion rate for every connected form plugin.
* **Campaign & UTM Builder** – Build, save, and auto-normalize tracking links, automatically matched back to real GA4 performance.
* **User Journey Tracking** – A visual path from first click to checkout, plus a saved journey timeline on every WooCommerce order.
* **Audience & Links** – Outbound clicks, file downloads, and GA4 age/gender demographics in one view.
* **Affiliate Link Tracking** – Dedicated partner and affiliate click classification, reporting by link, partner, and source page.
* **Exceptions Reporting** – JavaScript error tracking and GA4 traffic/conversion anomaly alerts, with email notifications.
* **Site Performance** – Google PageSpeed Insights scores, Core Web Vitals, and prioritized fix recommendations.
* **Advanced Reporting & AI Analytics (Ask AI)** – Plain-English questions answered from live GA4 data, plus structured Advanced Reports tabs.
* **Site Notes & Annotations** – Pin dated notes directly onto your GA4 traffic charts for launches, campaigns, and changes.
* **Popular Posts** – GA4-ranked content, displayed via widget, Gutenberg block, or shortcode.
* **Media Tracking** – Video engagement funnel (start, 25/50/75% milestones, completion) for YouTube, Vimeo, and HTML5 video.
* **AMP Tracking** – GA4 pageview reporting for AMP pages, compared directly against standard pages.
* **Custom Dimensions** – Sends post type, category, author, and SEO data to GA4 so every report and AI answer is more specific.
* **EU Compliance & Privacy** – Consent-gated tracking, PII stripping, and a visitor-facing opt-out for GDPR-conscious sites.
* **PPC Ads Tracking** – Unified conversion tracking across Google Ads, Microsoft Ads, Meta, TikTok, LinkedIn, Pinterest, and Snapchat.
* **Page Insights** – On-demand GA4 stats for a single post or page, right in the editor sidebar and posts list.

See the full feature breakdown and pricing on the [WP Pulse Analytics Pro product page](https://www.smackcoders.com/ga4-analytics-plugin-for-wordpress.html?utm_source=wordpress_org&utm_medium=readme&utm_campaign=pulse_analytics_free&utm_content=pro_features_link).

= Important Notes =

* Requires WordPress 6.4 or higher and PHP 7.4 or higher
* Requires a Google Analytics 4 property; Universal Analytics is not supported
* Works on any WordPress site; a store plugin (WooCommerce, Easy Digital Downloads, MemberPress, or GiveWP) is only needed for revenue and order reports
* All 20 features listed above under Pro Features require WP Pulse Analytics Pro; the Free plugin provides the core dashboard, real-time visitors, affiliate link tracking, and free-tier form submission tracking
* If you're upgrading from a version prior to 2.0, WP Pulse Analytics now requests an expanded Google OAuth scope to support Custom Dimensions provisioning; reconnecting your GA4 account under Settings is recommended after updating

== Installation ==

I. For a simple general way to install

* Login to your WordPress Admin (e.g. yourdomain.com/wp-admin/)
* Go to Plugins >> Add New
* Select the tab "Upload"
* Browse and Upload the downloaded zip file
* Activate the plugin after install
* You can see a new menu Pulse Analytics in your Admin now

II. For familiar FTP users

* Extract the plugin zip
* Upload plugin zip to /wp-content/plugins/
* Go to Plugins >> Installed Plugins >> Inactive
* Click Activate to activate the plugin
* You can see a new menu Pulse Analytics in your Admin now

III. Straight from WordPress Admin

* Login to your WordPress Admin (e.g. yourdomain.com/wp-admin/)
* Go to Plugins >> Add New
* Search for Pulse Analytics
* Click Install Now to install
* Activate the plugin after install
* You can see a new menu Pulse Analytics in your Admin now

= Connect Google Analytics 4 =

* Go to Pulse Analytics >> Settings >> Analytics Configuration
* Enter your GA4 Measurement ID and Property ID
* Enter your OAuth Client ID and Client Secret from Google Cloud Console
* Open Authorized Connection and click Connect with Google
* Go to Pulse Analytics >> Dashboard and click Sync Data

== Frequently Asked Questions ==

= 1. Do I need a Google Analytics account to use this plugin? =
Yes. Create a free GA4 property at analytics.google.com before connecting Pulse Analytics to it.

= 2. Do I need WooCommerce to use this plugin? =
No. The traffic dashboard, real-time visitors, and Core Web Vitals work on any WordPress site. Revenue and order reports activate automatically once WooCommerce, Easy Digital Downloads, MemberPress, or GiveWP is detected.

= 3. Can I track the journey a particular customer took before they purchased? =
Yes. Pro adds a User Journey view directly on the WooCommerce order screen, showing the pages that customer visited before checkout, along with a site-wide journey and drop-off funnel report.

= 4. Does this plugin track affiliate and outbound links automatically? =
Yes, in both Free and Pro. Once you set your affiliate URL prefixes or partner domains in Settings, every matching click is classified and reported without any manual link tagging; Pro adds a fuller report broken down by partner and source page.

= 5. Is this plugin GDPR compatible? =
Pulse Analytics includes consent-gated tracking and PII stripping under Settings >> Privacy & Compliance. You are still responsible for your own consent banner and privacy policy.

= 6. Where is my data stored? =
Your analytics numbers come live from your own GA4 property. Some events, such as link clicks, are cached locally in your WordPress database for faster report loading. OAuth credentials are stored encrypted.

= 7. Can I ask questions about my site's performance instead of building a report? =
Yes, with Pro. The Ask AI assistant answers plain-English questions using a live query to your own GA4 data, with a written explanation and the key metrics behind it.

= 8. Does Pulse Analytics show my Google Search Console data too? =
Yes, with Pro. Search queries, impressions, click-through rate, and average position are available in a dedicated Search Console report once connected.

= 9. Can I track PPC ad conversions from multiple ad platforms? =
Yes, with Pro. Google Ads, Microsoft Ads, Meta, TikTok, LinkedIn, Pinterest, and Snapchat conversions can all be sent from one settings screen, tied to WooCommerce orders and form submissions.

= 10. Where can I find full documentation? =
The complete setup guide and feature documentation is available at [Pulse Analytics Docs](https://www.smackcoders.com/documentation/pulse-analytics?utm_source=wordpress_org&utm_medium=readme&utm_campaign=pulse_analytics_free&utm_content=faq_docs_link).

== Screenshots ==

1. Dashboard Overview
2. Audience and Links
3. Affiliate Link Tracking
4. General Setting
5. Analytics Configuration
6. Downloads & Link Paths
7. Affiliate Link Tracking

== Changelog ==

= 2.0 = 

* Improved: Overall plugin stability and performance.
* Improved: Fixed minor issues and improved compatibility.
* Improved: Updated plugin documentation and release information.
* Added: GA4-powered Dashboard (Free) with live traffic analytics from Google Analytics 4 — active visitors (real-time), sessions with vs. last period comparison, page views with pages/session, average session duration with period delta, engagement rate, new vs. returning visitor split, device type breakdown (Mobile, Desktop, Tablet), browser used percentages, Top Pages table (page path and views), and Visitor Geography table (country and visitors).
* Added: Affiliate Link Tracking module with frontend click tracker, link classifier, Affiliate Links admin report, period comparison, and settings tab.
* Added: Forms Conversion Tracking engine with auto-discovery for Contact Form 7, Gravity Forms, WPForms, Ninja Forms, and Forminator — form submits are tracked to GA4 in Free; the Forms Conversion analytics report requires Pulse Analytics Pro.
* Added: Forms Conversion admin report page (Pro overlay in Free; live GA4 report data unlocked with a Pro license).
* Added: Session heartbeat and page engagement tracking via REST endpoints for active sessions and time-on-page telemetry.
* Added: Custom Dimensions framework hooks for gtag and Measurement Protocol integration.
* Added: Free-tier REST endpoints for link-click and demographic report previews with demo-data UI.
* Added: Dashboard traffic trend chart with dual-axis curves, dynamic KPI card updates, and key-event tooltips on engagement metrics.
* Added: Global admin date picker with custom date range across Dashboard, Affiliate Links, Campaign Builder, and AMP reports.
* Added: Pro module detection helpers for all bundled Pro feature modules.
* Improved: Rebranded WooPulse to Pulse Analytics for WordPress across menus, text domain, and admin copy.
* Improved: Consolidated Core Web Vitals under the Site Performance menu slug.
* Improved: Expanded Google OAuth scopes to include analytics.edit for Custom Dimensions provisioning.
* Improved: Event tracking migrated from local database storage (legacy Woo Customer Insight wci_* tables) to Google Analytics 4 — page views, clicks, form submits, link clicks, and commerce events are sent to GA4 via gtag; dashboard KPIs and reports are now powered by the GA4 Data API instead of local event tables.
* Improved: REST API access for users with the manage_options capability alongside Pulse-specific capabilities.
* Improved: Centralized settings handling with sanitized admin inputs and encrypted credential storage.
* Improved: Responsive admin UI with a consistent design system, loading states, and calendar navigation fixes.
* Improved: Pro affiliate deduplication — the Free link-click tracker defers when the Pro affiliate module is active.
* Fixed: Duplicate gtag injection and conflicting manual page_view calls with custom dimensions.
* Compatibility: WordPress 6.4+ (tested up to 7.0), PHP 7.4+, WooCommerce 8.0+ optional with HPOS support.

= 1.0.2 =

* Added: Universal site support, the plugin now works on blogs and business sites without WooCommerce.
* Added: Site profile with auto-detect, Website, or Online store modes.
* Added: Multi-platform commerce detection for WooCommerce, Easy Digital Downloads, MemberPress, and GiveWP.
* Added: Translation-ready strings with POT template.

= 1.0.1 =

* Added: Free dashboard live visitors KPI, date presets, and sync timestamp.
* Added: Link-click tracking and frontend capture.
* Fixed: Packaging for WordPress.org submission.

= 1.0.0 =

* Initial public release.
* GA4 OAuth connection and dashboard with traffic KPIs and charts.
* Settings wizard, privacy controls, and link-tracking configuration.

== Upgrade Notice ==

= 2.0 =

This release includes improvements, fixes, and updated plugin information. Update to version 2.0 for the latest GA4 Analytics for WordPress & WooCommerce.
